bpo-20064: Document PyObject_Malloc() (#4204)

Document the following functions:

* PyObject_Malloc()
* PyObject_Realloc()
* PyObject_Free()

Document also the pymalloc allocator.

2 files changed, 83 insertions, 1 deletions

diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 5465571..258898d 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 1bb1866..5655554 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)