@@ -102,34 +102,38 @@ All allocating functions belong to one of three different "domains" (see also
102
102
strategies and are optimized for different purposes. The specific details on
103
103
how every domain allocates memory or what internal functions each domain calls
104
104
is considered an implementation detail, but for debugging purposes a simplified
105
- table can be found at :ref: `here <default-memory-allocators >`. In the default build,
106
- there is no hard requirement to use the memory returned by the allocation functions
107
- belonging to a given domain for only the purposes hinted by that domain.
108
- (although this is the recommended practice). For example, one could use the memory
109
- returned by :c:func: `PyMem_RawMalloc ` for allocating Python objects or the memory
110
- returned by :c:func: `PyObject_Malloc ` for allocating memory for buffers.
111
- However, in the free-threaded build, Python objects must be allocated through :c:func: `PyObject_Malloc `.
112
- Non-Python objects must not be allocated this function, for example, it is currently acceptable to
113
- allocate buffers(non-Python objects) through :c:func: `PyObject_Malloc `; that will no longer be allowed
114
- and buffers should instead be allocated through :c:func: `PyMem_Malloc `, :c:func: `PyMem_RawMalloc `, or :c:func: `malloc `.
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 `.
115
108
116
109
The three allocation domains are:
117
110
118
111
* Raw domain: intended for allocating memory for general-purpose memory
119
112
buffers where the allocation *must * go to the system allocator or where the
120
113
allocator can operate without the :term: `GIL `. The memory is requested directly
121
- to the system.
114
+ from the system. See :ref: ` Raw Memory Interface < raw-memoryinterface >` .
122
115
123
116
* "Mem" domain: intended for allocating memory for Python buffers and
124
117
general-purpose memory buffers where the allocation must be performed with
125
118
the :term: `GIL ` held. The memory is taken from the Python private heap.
119
+ See :ref: `Memory Interface <memoryinterface >`.
126
120
127
- * Object domain: intended for allocating memory belonging to Python objects. The
128
- 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 >`.
129
123
130
- When freeing memory previously allocated by the allocating functions belonging to a
131
- given domain,the matching specific deallocating functions must be used. For example,
132
- :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 :
133
137
134
138
Raw Memory Interface
135
139
====================
@@ -303,6 +307,8 @@ versions and is therefore deprecated in extension modules.
303
307
* ``PyMem_DEL(ptr) ``
304
308
305
309
310
+ .. _objectinterface :
311
+
306
312
Object allocators
307
313
=================
308
314
0 commit comments