From f27c153e6cb5781f79b2077a066b9804a5700835 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Mon, 18 Jan 2021 21:53:44 +0000 Subject: [PATCH 1/2] Add a paragraph about allocation domains to the C-API docs --- Doc/c-api/memory.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 87425bcf1e71f2..c356452c6f19c7 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -92,6 +92,38 @@ for the I/O buffer escapes completely the Python memory manager. statistics of the :ref:`pymalloc memory allocator ` 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 `. 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 ==================== From 64e1617e374067a36eef2752bc1aeca622877624 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Mon, 18 Jan 2021 22:03:28 +0000 Subject: [PATCH 2/2] Update Doc/c-api/memory.rst Co-authored-by: Victor Stinner --- Doc/c-api/memory.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index c356452c6f19c7..bd73780cc0f8e8 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -114,7 +114,7 @@ The three allocation domains are: 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 +* "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. @@ -633,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. -