@@ -102,30 +102,38 @@ All allocating functions belong to one of three different "domains" (see also
102102strategies and are optimized for different purposes. The specific details on
103103how every domain allocates memory or what internal functions each domain calls
104104is considered an implementation detail, but for debugging purposes a simplified
105- table can be found at :ref: `here <default-memory-allocators >`. There is no hard
106- requirement to use the memory returned by the allocation functions belonging to
107- a given domain for only the purposes hinted by that domain (although this is the
108- recommended practice). For example, one could use the memory returned by
109- :c:func: `PyMem_RawMalloc ` for allocating Python objects or the memory returned
110- by :c:func: `PyObject_Malloc ` for allocating memory for buffers.
105+ table can be found at :ref: `here <default-memory-allocators >`.
106+ The APIs used to allocate and free a block of memory must be from the same domain.
107+ For example, :c:func: `PyMem_Free ` must be used to free memory allocated using :c:func: `PyMem_Malloc `.
111108
112109The three allocation domains are:
113110
114111* Raw domain: intended for allocating memory for general-purpose memory
115112 buffers where the allocation *must * go to the system allocator or where the
116113 allocator can operate without the :term: `GIL `. The memory is requested directly
117- to the system.
114+ from the system. See :ref: ` Raw Memory Interface < raw-memoryinterface >` .
118115
119116* "Mem" domain: intended for allocating memory for Python buffers and
120117 general-purpose memory buffers where the allocation must be performed with
121118 the :term: `GIL ` held. The memory is taken from the Python private heap.
119+ See :ref: `Memory Interface <memoryinterface >`.
122120
123- * Object domain: intended for allocating memory belonging to Python objects. The
124- memory is taken from the Python private heap.
121+ * Object domain: intended for allocating memory for Python objects. The
122+ memory is taken from the Python private heap. See :ref: ` Object allocators < objectinterface >`.
125123
126- When freeing memory previously allocated by the allocating functions belonging to a
127- given domain,the matching specific deallocating functions must be used. For example,
128- :c:func: `PyMem_Free ` must be used to free memory allocated using :c:func: `PyMem_Malloc `.
124+ .. note ::
125+
126+ The :term: `free-threaded <free threading> ` build requires that only Python objects are allocated using the "object" domain
127+ and that all Python objects are allocated using that domain. This differs from the prior Python versions,
128+ where this was only a best practice and not a hard requirement.
129+
130+ For example, buffers (non-Python objects) should be allocated using :c:func: `PyMem_Malloc `,
131+ :c:func: `PyMem_RawMalloc `, or :c:func: `malloc `, but not :c:func: `PyObject_Malloc `.
132+
133+ See :ref: `Memory Allocation APIs <free-threaded-memory-allocation >`.
134+
135+
136+ .. _raw-memoryinterface :
12913
8000
7
130138Raw Memory Interface
131139====================
@@ -299,6 +307,8 @@ versions and is therefore deprecated in extension modules.
299307* ``PyMem_DEL(ptr) ``
300308
301309
310+ .. _objectinterface :
311+
302312Object allocators
303313=================
304314
0 commit comments