diff options
| -rw-r--r-- | Doc/api/api.tex | 105 | ||||
| -rw-r--r-- | Doc/api/refcounts.dat | 11 |
2 files changed, 62 insertions, 54 deletions
diff --git a/Doc/api/api.tex b/Doc/api/api.tex index fe56705..f75768a 100644 --- a/Doc/api/api.tex +++ b/Doc/api/api.tex @@ -4351,39 +4351,35 @@ returned by a previous call to \cfunction{PyMem_Malloc()} or occurs. If \var{p} is \NULL{}, no operation is performed. \end{cfuncdesc} -\begin{cfuncdesc}{void*}{Py_Malloc}{size_t n} -Same as \cfunction{PyMem_Malloc()}, but calls -\cfunction{PyErr_NoMemory()} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{void*}{Py_Realloc}{void *p, size_t n} -Same as \cfunction{PyMem_Realloc()}, but calls -\cfunction{PyErr_NoMemory()} on failure. -\end{cfuncdesc} - -\begin{cfuncdesc}{void}{Py_Free}{void *p} -Same as \cfunction{PyMem_Free()}. -\end{cfuncdesc} - The following type-oriented macros are provided for convenience. Note that \var{TYPE} refers to any C type. -\begin{cfuncdesc}{\var{TYPE}*}{PyMem_NEW}{TYPE, size_t n} +\begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n} Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} * sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to \ctype{\var{TYPE}*}. \end{cfuncdesc} -\begin{cfuncdesc}{\var{TYPE}*}{PyMem_RESIZE}{void *p, TYPE, size_t n} +\begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n} Same as \cfunction{PyMem_Realloc()}, but the memory block is resized to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer cast to \ctype{\var{TYPE}*}. \end{cfuncdesc} -\begin{cfuncdesc}{void}{PyMem_DEL}{void *p} +\begin{cfuncdesc}{void}{PyMem_Del}{void *p} Same as \cfunction{PyMem_Free()}. \end{cfuncdesc} +In addition, the following macro sets are provided for calling the +Python memory allocator directly, without involving the C API functions +listed above. However, note that their use does not preserve binary +compatibility accross Python versions and is therefore deprecated in +extension modules. + +\cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}. + +\cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}. + \section{Examples \label{memoryExamples}} @@ -4403,37 +4399,22 @@ first function set: return res; \end{verbatim} -With the second function set, the need to call -\cfunction{PyErr_NoMemory()} is obviated: - -\begin{verbatim} - PyObject *res; - char *buf = (char *) Py_Malloc(BUFSIZ); /* for I/O */ - - if (buf == NULL) - return NULL; - /* ...Do some I/O operation involving buf... */ - res = PyString_FromString(buf); - Py_Free(buf); /* allocated with Py_Malloc */ - return res; -\end{verbatim} - -The same code using the macro set: +The same code using the type-oriented function set: \begin{verbatim} PyObject *res; - char *buf = PyMem_NEW(char, BUFSIZ); /* for I/O */ + char *buf = PyMem_New(char, BUFSIZ); /* for I/O */ if (buf == NULL) return PyErr_NoMemory(); /* ...Do some I/O operation involving buf... */ res = PyString_FromString(buf); - PyMem_DEL(buf); /* allocated with PyMem_NEW */ + PyMem_Del(buf); /* allocated with PyMem_New */ return res; \end{verbatim} -Note that in the three examples above, the buffer is always -manipulated via functions/macros belonging to the same set. Indeed, it +Note that in the two examples above, the buffer is always +manipulated via functions belonging to the same set. Indeed, it is required to use the same memory API family for a given memory block, so that the risk of mixing different allocators is reduced to a minimum. The following code sequence contains two errors, @@ -4441,26 +4422,20 @@ one of which is labeled as \emph{fatal} because it mixes two different allocators operating on different heaps. \begin{verbatim} -char *buf1 = PyMem_NEW(char, BUFSIZ); +char *buf1 = PyMem_New(char, BUFSIZ); char *buf2 = (char *) malloc(BUFSIZ); char *buf3 = (char *) PyMem_Malloc(BUFSIZ); ... -PyMem_DEL(buf3); /* Wrong -- should be PyMem_Free() */ +PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */ free(buf2); /* Right -- allocated via malloc() */ -free(buf1); /* Fatal -- should be PyMem_DEL() */ +free(buf1); /* Fatal -- should be PyMem_Del() */ \end{verbatim} In addition to the functions aimed at handling raw memory blocks from the Python heap, objects in Python are allocated and released with -\cfunction{_PyObject_New()}\ttindex{_PyObject_New()} and -\cfunction{_PyObject_NewVar()}\ttindex{_PyObject_NewVar()}, or with -their corresponding macros -\cfunction{PyObject_NEW()}\ttindex{PyObject_NEW()} and -\cfunction{PyObject_NEW_VAR()}\ttindex{PyObject_NEW_VAR()}. - -\cfunction{_PyObject_New()}, \cfunction{_PyObject_NewVar()}, -\cfunction{_PyObject_Del()}, or with their corresponding macros -\cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()}, +\cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and +\cfunction{PyObject_Del()}, or with their corresponding macros +\cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and \cfunction{PyObject_DEL()}. These will be explained in the next chapter on defining and @@ -4472,14 +4447,38 @@ implementing new object types in C. \begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type} \end{cfuncdesc} -\begin{cfuncdesc}{PyObject*}{_PyObject_NewVar}{PyTypeObject *type, int size} +\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op, + PyTypeObject *type} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op, + PyTypeObject *type, int size} +\end{cfuncdesc} + +\begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type} +\end{cfuncdesc} + +\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type, + int size} +\end{cfuncdesc} + +\begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op} +\end{cfuncdesc} + +\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type} \end{cfuncdesc} -\begin{cfuncdesc}{\var{TYPE}}{_PyObject_NEW}{TYPE, PyTypeObject *type} +\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type, + int size} \end{cfuncdesc} -\begin{cfuncdesc}{\var{TYPE}}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *type, - int size} +\begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op} \end{cfuncdesc} Py_InitModule (!!!) diff --git a/Doc/api/refcounts.dat b/Doc/api/refcounts.dat index 09a727e..0a80d67 100644 --- a/Doc/api/refcounts.dat +++ b/Doc/api/refcounts.dat @@ -609,6 +609,12 @@ PyObject_Hash:PyObject*:o:0: PyObject_IsTrue:int::: PyObject_IsTrue:PyObject*:o:0: +PyObject_Init:PyObject*::0: +PyObject_Init:PyObject*:op:0: + +PyObject_InitVar:PyVarObject*::0: +PyObject_InitVar:PyVarObject*:op:0: + PyObject_Length:int::: PyObject_Length:PyObject*:o:0: @@ -1212,10 +1218,13 @@ _PyImport_FixupExtension:char*::: _PyImport_Init:void::: +_PyObject_Del:void::: +_PyObject_Del:PyObject*:op:0: + _PyObject_New:PyObject*::+1: _PyObject_New:PyTypeObject*:type:0: -_PyObject_NewVar:PyObject*::+1: +_PyObject_NewVar:PyVarObject*::+1: _PyObject_NewVar:PyTypeObject*:type:0: _PyObject_NewVar:int:size:: |