[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.82,1.83 refcounts.dat,1.15,1.16
Fred L. Drake
python-dev@python.org
Tue, 12 Sep 2000 13:17:20 -0700
Update of /cvsroot/python/python/dist/src/Doc/api
In directory slayer.i.sourceforge.net:/tmp/cvs-serv8306
Modified Files:
api.tex refcounts.dat
Log Message:
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Here are some changes to the C API docs. The memory examples & API have
been updated because one malloc family is gone (Py_Malloc).
You'll see other small additions to the "building new types" section
for completeness and some cleanup at the end of the memory section.
Index: api.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.82
retrieving revision 1.83
diff -C2 -r1.82 -r1.83
*** api.tex 2000/09/12 15:22:04 1.82
--- api.tex 2000/09/12 20:17:17 1.83
***************
*** 4352,4373 ****
\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}
Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} *
sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to
--- 4352,4359 ----
\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}
Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} *
sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to
***************
*** 4375,4379 ****
\end{cfuncdesc}
! \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
--- 4361,4365 ----
\end{cfuncdesc}
! \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
***************
*** 4381,4389 ****
\end{cfuncdesc}
! \begin{cfuncdesc}{void}{PyMem_DEL}{void *p}
Same as \cfunction{PyMem_Free()}.
\end{cfuncdesc}
\section{Examples \label{memoryExamples}}
--- 4367,4385 ----
\end{cfuncdesc}
! \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,4427 ****
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:
\begin{verbatim}
PyObject *res;
! char *buf = PyMem_NEW(char, BUFSIZ); /* for I/O */
if (buf == NULL)
--- 4399,4408 ----
return res;
\end{verbatim}
! The same code using the type-oriented function set:
\begin{verbatim}
PyObject *res;
! char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
if (buf == NULL)
***************
*** 4429,4438 ****
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
! 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
is required to use the same memory API family for a given
memory block, so that the risk of mixing different allocators is
--- 4410,4419 ----
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
! PyMem_Del(buf); /* allocated with PyMem_New */
return res;
\end{verbatim}
! 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
***************
*** 4442,4465 ****
\begin{verbatim}
! 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() */
free(buf2); /* Right -- allocated via malloc() */
! 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_DEL()}.
--- 4423,4440 ----
\begin{verbatim}
! 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() */
free(buf2); /* Right -- allocated via malloc() */
! 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()}, \cfunction{PyObject_NewVar()} and
! \cfunction{PyObject_Del()}, or with their corresponding macros
! \cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and
\cfunction{PyObject_DEL()}.
***************
*** 4472,4484 ****
\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
! \begin{cfuncdesc}{PyObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
\end{cfuncdesc}
! \begin{cfuncdesc}{\var{TYPE}}{_PyObject_NEW}{TYPE, PyTypeObject *type}
\end{cfuncdesc}
! \begin{cfuncdesc}{\var{TYPE}}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
! int size}
\end{cfuncdesc}
--- 4447,4483 ----
\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
\end{cfuncdesc}
+
+ \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_VAR}{TYPE, PyTypeObject *type,
! int size}
\end{cfuncdesc}
! \begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
\end{cfuncdesc}
Index: refcounts.dat
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/refcounts.dat,v
retrieving revision 1.15
retrieving revision 1.16
diff -C2 -r1.15 -r1.16
*** refcounts.dat 2000/09/12 15:22:05 1.15
--- refcounts.dat 2000/09/12 20:17:17 1.16
***************
*** 610,613 ****
--- 610,619 ----
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:
***************
*** 1213,1220 ****
_PyImport_Init:void:::
_PyObject_New:PyObject*::+1:
_PyObject_New:PyTypeObject*:type:0:
! _PyObject_NewVar:PyObject*::+1:
_PyObject_NewVar:PyTypeObject*:type:0:
_PyObject_NewVar:int:size::
--- 1219,1229 ----
_PyImport_Init:void:::
+ _PyObject_Del:void:::
+ _PyObject_Del:PyObject*:op:0:
+
_PyObject_New:PyObject*::+1:
_PyObject_New:PyTypeObject*:type:0:
! _PyObject_NewVar:PyVarObject*::+1:
_PyObject_NewVar:PyTypeObject*:type:0:
_PyObject_NewVar:int:size::