Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Add a paragraph about allocation domains to the C-API docs (GH-24252)

This commit is contained in:
Pablo Galindo 2021-01-18 22:20:57 +00:00 committed by GitHub
parent 916610ef90
commit bc450f9694
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
Doc/c-api/memory.rst
View File

@ -92,6 +92,38 @@ for the I/O buffer escapes completely the Python memory manager.
statistics of the :ref:`pymalloc memory allocator <pymalloc>` every time a
new pymalloc object arena is created, and on shutdown.
Allocator Domains
=================
All allocating functions belong to one of three different "domains" (see also
:c:type`PyMemAllocatorDomain`). These domains represent different allocation
strategies and are optimized for different purposes. The specific details on
how every domain allocates memory or what internal functions each domain calls
is considered an implementation detail, but for debugging purposes a simplified
table can be found at :ref:`here <default-memory-allocators>`. There is no hard
requirement to use the memory returned by the allocation functions belonging to
a given domain for only the purposes hinted by that domain (although this is the
recommended practice). For example, one could use the memory returned by
:c:func:`PyMem_RawMalloc` for allocating Python objects or the memory returned
by :c:func:`PyObject_Malloc` for allocating memory for buffers.
The three allocation domains are:
* Raw domain: intended for allocating memory for general-purpose memory
buffers where the allocation *must* go to the system allocator or where the
allocator can operate without the :term:`GIL`. The memory is requested directly
to the system.
* "Mem" domain: intended for allocating memory for Python buffers and
general-purpose memory buffers where the allocation must be performed with
the :term:`GIL` held. The memory is taken from the Python private heap.
* Object domain: intended for allocating memory belonging to Python objects. The
memory is taken from the Python private heap.
When freeing memory previously allocated by the allocating functions belonging to a
given domain,the matching specific deallocating functions must be used. For example,
:c:func:`PyMem_Free` must be used to free memory allocated using :c:func:`PyMem_Malloc`.
Raw Memory Interface
====================
@ -601,4 +633,3 @@ heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
These will be explained in the next chapter on defining and implementing new
object types in C.