https://github.com/python/cpython/commit/8543ce8ffd57d770b57fe653e0ab7fada1a... commit: 8543ce8ffd57d770b57fe653e0ab7fada1a4c343 branch: 3.6 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: Victor Stinner <victor.stinner@gmail.com> date: 2017-10-31T09:56:11-07:00 summary: bpo-20064: Document PyObject_Malloc() (GH-4199) (#4203) Document the following functions: * PyObject_Malloc() * PyObject_Calloc() * PyObject_Realloc() * PyObject_Free() Fix also PyMem_RawFree() documentation. (cherry picked from commit ec2cbdd1dff2c51788136480b2085e77506ebf34) files: M Doc/c-api/memory.rst diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 873fb2ac1d3..73bec7c95a1 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -150,7 +150,7 @@ The default raw memory block allocator uses the following functions: Frees the memory block pointed to by *p*, which must have been returned by a previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or - :c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_Free(p)`` has been + :c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been called before, undefined behavior occurs. If *p* is *NULL*, no operation is performed. @@ -263,6 +263,69 @@ versions and is therefore deprecated in extension modules. * ``PyMem_DEL(ptr)`` +Object allocators +================= + +The following function sets, modeled after the ANSI C standard, but specifying +behavior when requesting zero bytes, are available for allocating and releasing +memory from the Python heap. + +By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`. + +.. warning:: + + The :term:`GIL <global interpreter lock>` must be held when using these + functions. + +.. c:function:: void* PyObject_Malloc(size_t n) + + Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the + allocated memory, or *NULL* if the request fails. + + Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as + if ``PyObject_Malloc(1)`` had been called instead. The memory will not have + been initialized in any way. + + +.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize) + + Allocates *nelem* elements each whose size in bytes is *elsize* and returns + a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the + request fails. The memory is initialized to zeros. + + Requesting zero elements or elements of size zero bytes returns a distinct + non-*NULL* pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called + instead. + + .. versionadded:: 3.5 + + +.. c:function:: void* PyObject_Realloc(void *p, size_t n) + + Resizes the memory block pointed to by *p* to *n* bytes. The contents will be + unchanged to the minimum of the old and the new sizes. + + If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n* + is equal to zero, the memory block is resized but is not freed, and the + returned pointer is non-*NULL*. + + Unless *p* is *NULL*, it must have been returned by a previous call to + :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`. + + If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains + a valid pointer to the previous memory area. + + +.. c:function:: void PyObject_Free(void *p) + + Frees the memory block pointed to by *p*, which must have been returned by a + previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or + :c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called + before, undefined behavior occurs. + + If *p* is *NULL*, no operation is performed. + + Customize Memory Allocators ===========================