Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit f913e54

Browse files
freddrakefreddrake
committed
Vladimir Marangozov <[email protected]>:
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.
1 parent c568173 commit f913e54

2 files changed

Lines changed: 62 additions & 54 deletions

File tree

‎Doc/api/api.tex‎

Lines changed: 52 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -4351,39 +4351,35 @@ \section{Memory Interface \label{memoryInterface}}
43514351
occurs. If \var{p} is \NULL{}, no operation is performed.
43524352
\end{cfuncdesc}
43534353

4354-
\begin{cfuncdesc}{void*}{Py_Malloc}{size_t n}
4355-
Same as \cfunction{PyMem_Malloc()}, but calls
4356-
\cfunction{PyErr_NoMemory()} on failure.
4357-
\end{cfuncdesc}
4358-
4359-
\begin{cfuncdesc}{void*}{Py_Realloc}{void *p, size_t n}
4360-
Same as \cfunction{PyMem_Realloc()}, but calls
4361-
\cfunction{PyErr_NoMemory()} on failure.
4362-
\end{cfuncdesc}
4363-
4364-
\begin{cfuncdesc}{void}{Py_Free}{void *p}
4365-
Same as \cfunction{PyMem_Free()}.
4366-
\end{cfuncdesc}
4367-
43684354
The following type-oriented macros are provided for convenience. Note
43694355
that \var{TYPE} refers to any C type.
43704356

4371-
\begin{cfuncdesc}{\var{TYPE}*}{PyMem_NEW}{TYPE, size_t n}
4357+
\begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n}
43724358
Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} *
43734359
sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to
43744360
\ctype{\var{TYPE}*}.
43754361
\end{cfuncdesc}
43764362

4377-
\begin{cfuncdesc}{\var{TYPE}*}{PyMem_RESIZE}{void *p, TYPE, size_t n}
4363+
\begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n}
43784364
Same as \cfunction{PyMem_Realloc()}, but the memory block is resized
43794365
to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer
43804366
cast to \ctype{\var{TYPE}*}.
43814367
\end{cfuncdesc}
43824368

4383-
\begin{cfuncdesc}{void}{PyMem_DEL}{void *p}
4369+
\begin{cfuncdesc}{void}{PyMem_Del}{void *p}
43844370
Same as \cfunction{PyMem_Free()}.
43854371
\end{cfuncdesc}
43864372

4373+
In addition, the following macro sets are provided for calling the
4374+
Python memory allocator directly, without involving the C API functions
4375+
listed above. However, note that their use does not preserve binary
4376+
compatibility accross Python versions and is therefore deprecated in
4377+
extension modules.
4378+
4379+
\cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}.
4380+
4381+
\cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}.
4382+
43874383

43884384
\section{Examples \label{memoryExamples}}
43894385

@@ -4403,64 +4399,43 @@ \section{Examples \label{memoryExamples}}
44034399
return res;
44044400
\end{verbatim}
44054401

4406-
With the second function set, the need to call
4407-
\cfunction{PyErr_NoMemory()} is obviated:
4408-
4409-
\begin{verbatim}
4410-
PyObject *res;
4411-
char *buf = (char *) Py_Malloc(BUFSIZ); /* for I/O */
4412-
4413-
if (buf == NULL)
4414-
return NULL;
4415-
/* ...Do some I/O operation involving buf... */
4416-
res = PyString_FromString(buf);
4417-
Py_Free(buf); /* allocated with Py_Malloc */
4418-
return res;
4419-
\end{verbatim}
4420-
4421-
The same code using the macro set:
4402+
The same code using the type-oriented function set:
44224403

44234404
\begin{verbatim}
44244405
PyObject *res;
4425-
char *buf = PyMem_NEW(char, BUFSIZ); /* for I/O */
4406+
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
44264407
44274408
if (buf == NULL)
44284409
return PyErr_NoMemory();
44294410
/* ...Do some I/O operation involving buf... */
44304411
res = PyString_FromString(buf);
4431-
PyMem_DEL(buf); /* allocated with PyMem_NEW */
4412+
PyMem_Del(buf); /* allocated with PyMem_New */
44324413
return res;
44334414
\end{verbatim}
44344415

4435-
Note that in the three examples above, the buffer is always
4436-
manipulated via functions/macros belonging to the same set. Indeed, it
4416+
Note that in the two examples above, the buffer is always
4417+
manipulated via functions belonging to the same set. Indeed, it
44374418
is required to use the same memory API family for a given
44384419
memory block, so that the risk of mixing different allocators is
44394420
reduced to a minimum. The following code sequence contains two errors,
44404421
one of which is labeled as \emph{fatal} because it mixes two different
44414422
allocators operating on different heaps.
44424423

44434424
\begin{verbatim}
4444-
char *buf1 = PyMem_NEW(char, BUFSIZ);
4425+
char *buf1 = PyMem_New(char, BUFSIZ);
44454426
char *buf2 = (char *) malloc(BUFSIZ);
44464427
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
44474428
...
4448-
PyMem_DEL(buf3); /* Wrong -- should be PyMem_Free() */
4429+
PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
44494430
free(buf2); /* Right -- allocated via malloc() */
4450-
free(buf1); /* Fatal -- should be PyMem_DEL() */
4431+
free(buf1); /* Fatal -- should be PyMem_Del() */
44514432
\end{verbatim}
44524433

44534434
In addition to the functions aimed at handling raw memory blocks from
44544435
the Python heap, objects in Python are allocated and released with
4455-
\cfunction{_PyObject_New()}\ttindex{_PyObject_New()} and
4456-
\cfunction{_PyObject_NewVar()}\ttindex{_PyObject_NewVar()}, or with
4457-
their corresponding macros
4458-
\cfunction{PyObject_NEW()}\ttindex{PyObject_NEW()} and
4459-
\cfunction{PyObject_NEW_VAR()}\ttindex{PyObject_NEW_VAR()}.
4460-
4461-
\cfunction{_PyObject_New()}, \cfunction{_PyObject_NewVar()},
4462-
\cfunction{_PyObject_Del()}, or with their corresponding macros
4463-
\cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()},
4436+
\cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and
4437+
\cfunction{PyObject_Del()}, or with their corresponding macros
4438+
\cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and
44644439
\cfunction{PyObject_DEL()}.
44654440

44664441
These will be explained in the next chapter on defining and
@@ -4472,14 +4447,38 @@ \chapter{Defining New Object Types \label{newTypes}}
44724447
\begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
44734448
\end{cfuncdesc}
44744449

4475-
\begin{cfuncdesc}{PyObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
4450+
\begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
4451+
\end{cfuncdesc}
4452+
4453+
\begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
4454+
\end{cfuncdesc}
4455+
4456+
\begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op,
4457+
PyTypeObject *type}
4458+
\end{cfuncdesc}
4459+
4460+
\begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op,
4461+
PyTypeObject *type, int size}
4462+
\end{cfuncdesc}
4463+
4464+
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type}
4465+
\end{cfuncdesc}
4466+
4467+
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type,
4468+
int size}
4469+
\end{cfuncdesc}
4470+
4471+
\begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
4472+
\end{cfuncdesc}
4473+
4474+
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type}
44764475
\end{cfuncdesc}
44774476

4478-
\begin{cfuncdesc}{\var{TYPE}}{_PyObject_NEW}{TYPE, PyTypeObject *type}
4477+
\begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
4478+
int size}
44794479
\end{cfuncdesc}
44804480

4481-
\begin{cfuncdesc}{\var{TYPE}}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
4482-
int size}
4481+
\begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
44834482
\end{cfuncdesc}
44844483

44854484
Py_InitModule (!!!)

‎Doc/api/refcounts.dat‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -609,6 +609,12 @@ PyObject_Hash:PyObject*:o:0:
609609
PyObject_IsTrue:int:::
610610
PyObject_IsTrue:PyObject*:o:0:
611611

612+
PyObject_Init:PyObject*::0:
613+
PyObject_Init:PyObject*:op:0:
614+
615+
PyObject_InitVar:PyVarObject*::0:
616+
PyObject_InitVar:PyVarObject*:op:0:
617+
612618
PyObject_Length:int:::
613619
PyObject_Length:PyObject*:o:0:
614620

@@ -1212,10 +1218,13 @@ _PyImport_FixupExtension:char*:::
12121218

12131219
_PyImport_Init:void:::
12141220

1221+
_PyObject_Del:void:::
1222+
_PyObject_Del:PyObject*:op:0:
1223+
12151224
_PyObject_New:PyObject*::+1:
12161225
_PyObject_New:PyTypeObject*:type:0:
12171226

1218-
_PyObject_NewVar:PyObject*::+1:
1227+
_PyObject_NewVar:PyVarObject*::+1:
12191228
_PyObject_NewVar:PyTypeObject*:type:0:
12201229
_PyObject_NewVar:int:size::
12211230

0 commit comments

Comments
 (0)