[Python-checkins] bpo-20064: Document PyObject_Malloc() (GH-4199) (#4203)
Victor Stinner
webhook-mailer at python.org
Tue Oct 31 12:56:18 EDT 2017
https://github.com/python/cpython/commit/8543ce8ffd57d770b57fe653e0ab7fada1a4c343
commit: 8543ce8ffd57d770b57fe653e0ab7fada1a4c343
branch: 3.6
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Victor Stinner <victor.stinner at 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
===========================
More information about the Python-checkins
mailing list