[Python-checkins] bpo-20064: Document PyObject_Malloc() (#4204)
Victor Stinner
webhook-mailer at python.org
Tue Oct 31 13:08:31 EDT 2017
https://github.com/python/cpython/commit/52ba7b447f41dad2754ddbc50ed97413b557bbe1
commit: 52ba7b447f41dad2754ddbc50ed97413b557bbe1
branch: 2.7
author: Victor Stinner <victor.stinner at gmail.com>
committer: GitHub <noreply at github.com>
date: 2017-10-31T10:08:28-07:00
summary:
bpo-20064: Document PyObject_Malloc() (#4204)
Document the following functions:
* PyObject_Malloc()
* PyObject_Realloc()
* PyObject_Free()
Document also the pymalloc allocator.
files:
M Doc/c-api/memory.rst
M Objects/obmalloc.c
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 54655719045..258898d8702 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -155,6 +155,88 @@ versions and is therefore deprecated in extension modules.
:c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`.
+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_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.
+
+
+In addition, the following macro sets are provided:
+
+* :c:func:`PyObject_MALLOC`: alias to :c:func:`PyObject_Malloc`
+* :c:func:`PyObject_REALLOC`: alias to :c:func:`PyObject_Realloc`
+* :c:func:`PyObject_FREE`: alias to :c:func:`PyObject_Free`
+* :c:func:`PyObject_Del`: alias to :c:func:`PyObject_Free`
+* :c:func:`PyObject_DEL`: alias to :c:func:`PyObject_FREE` (so finally an alias
+ to :c:func:`PyObject_Free`)
+
+
+.. _pymalloc:
+
+The pymalloc allocator
+======================
+
+Python has a *pymalloc* allocator optimized for small objects (smaller or equal
+to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
+with a fixed size of 256 KiB. It falls back to :c:func:`malloc` and
+:c:func:`realloc` for allocations larger than 512 bytes.
+
+*pymalloc* is the default allocator of :c:func:`PyObject_Malloc`.
+
+The arena allocator uses the following functions:
+
+* :c:func:`mmap` and :c:func:`munmap` if available,
+* :c:func:`malloc` and :c:func:`free` otherwise.
+
+.. versionchanged:: 2.7.7
+ The threshold changed from 256 to 512 bytes. The arena allocator now
+ uses :c:func:`mmap` if available.
+
+
.. _memoryexamples:
Examples
diff --git a/Objects/obmalloc.c b/Objects/obmalloc.c
index 1bb1866dc6f..5655554b82d 100644
--- a/Objects/obmalloc.c
+++ b/Objects/obmalloc.c
@@ -214,7 +214,7 @@ static int running_on_valgrind = -1;
* Arenas are allocated with mmap() on systems supporting anonymous memory
* mappings to reduce heap fragmentation.
*/
-#define ARENA_SIZE (256 << 10) /* 256KB */
+#define ARENA_SIZE (256 << 10) /* 256KiB */
#ifdef WITH_MEMORY_LIMITS
#define MAX_ARENAS (SMALL_MEMORY_LIMIT / ARENA_SIZE)
More information about the Python-checkins
mailing list