8000 Address code review · python/cpython@db3acd2 · GitHub
[go: up one dir, main page]

Skip to content

Commit db3acd2

Browse files
committed
Address code review
1 parent a92d938 commit db3acd2

File tree

2 files changed

+24
-16
lines changed

2 files changed

+24
-16
lines changed

Doc/c-api/memory.rst

Lines changed: 22 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -102,34 +102,38 @@ All allocating functions belong to one of three different "domains" (see also
102102
strategies and are optimized for different purposes. The specific details on
103103
how every domain allocates memory or what internal functions each domain calls
104104
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`.
115108

116109
The three allocation domains are:
117110

118111
* Raw domain: intended for allocating memory for general-purpose memory
119112
buffers where the allocation *must* go to the system allocator or where the
120113
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>`.
122115

123116
* "Mem" domain: intended for allocating memory for Python buffers and
124117
general-purpose memory buffers where the allocation must be performed with
125118
the :term:`GIL` held. The memory is taken from the Python private heap.
119+
See :ref:`Memory Interface <memoryinterface>`.
126120

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>`.
129123

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:
133137

134138
Raw Memory Interface
135139
====================
@@ -303,6 +307,8 @@ versions and is therefore deprecated in extension modules.
303307
* ``PyMem_DEL(ptr)``
304308
305309
310+
.. _objectinterface:
311+
306312
Object allocators
307313
=================
308314

Doc/howto/free-threading-extensions.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,8 @@ to provide implementations of these functions for older Python versions.
184184
Memory Allocation APIs
185185
======================
186186

187+
.. _free-threaded-memory-allocation:
188+
187189
Python's memory management C API provides functions in three different
188190
:ref:`allocation domains <allocator-domains>`: "raw", "mem", and "object".
189191
For thread-safety, the free-threaded build requires that only Python objects

0 commit comments

Comments
 (0)
0