| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
|
| 4 |
.. _memory: |
| 5 |
|
| 6 |
***************** |
| 7 |
Memory Management |
| 8 |
***************** |
| 9 |
|
| 10 |
.. sectionauthor:: Vladimir Marangozov <[email protected]> |
| 11 |
|
| 12 |
|
| 13 |
|
| 14 |
.. _memoryoverview: |
| 15 |
|
| 16 |
Overview |
| 17 |
======== |
| 18 |
|
| 19 |
Memory management in Python involves a private heap containing all Python |
| 20 |
objects and data structures. The management of this private heap is ensured |
| 21 |
internally by the *Python memory manager*. The Python memory manager has |
| 22 |
different components which deal with various dynamic storage management aspects, |
| 23 |
like sharing, segmentation, preallocation or caching. |
| 24 |
|
| 25 |
At the lowest level, a raw memory allocator ensures that there is enough room in |
| 26 |
the private heap for storing all Python-related data by interacting with the |
| 27 |
memory manager of the operating system. On top of the raw memory allocator, |
| 28 |
several object-specific allocators operate on the same heap and implement |
| 29 |
distinct memory management policies adapted to the peculiarities of every object |
| 30 |
type. For example, integer objects are managed differently within the heap than |
| 31 |
strings, tuples or dictionaries because integers imply different storage |
| 32 |
requirements and speed/space tradeoffs. The Python memory manager thus delegates |
| 33 |
some of the work to the object-specific allocators, but ensures that the latter |
| 34 |
operate within the bounds of the private heap. |
| 35 |
|
| 36 |
It is important to understand that the management of the Python heap is |
| 37 |
performed by the interpreter itself and that the user has no control over it, |
| 38 |
even if they regularly manipulate object pointers to memory blocks inside that |
| 39 |
heap. The allocation of heap space for Python objects and other internal |
| 40 |
buffers is performed on demand by the Python memory manager through the Python/C |
| 41 |
API functions listed in this document. |
| 42 |
|
| 43 |
.. index:: |
| 44 |
single: malloc (C function) |
| 45 |
single: calloc (C function) |
| 46 |
single: realloc (C function) |
| 47 |
single: free (C function) |
| 48 |
|
| 49 |
To avoid memory corruption, extension writers should never try to operate on |
| 50 |
Python objects with the functions exported by the C library: :c:func:`malloc`, |
| 51 |
:c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will result in mixed |
| 52 |
calls between the C allocator and the Python memory manager with fatal |
| 53 |
consequences, because they implement different algorithms and operate on |
| 54 |
different heaps. However, one may safely allocate and release memory blocks |
| 55 |
with the C library allocator for individual purposes, as shown in the following |
| 56 |
example:: |
| 57 |
|
| 58 |
PyObject *res; |
| 59 |
char *buf = (char *) malloc(BUFSIZ); /* for I/O */ |
| 60 |
|
| 61 |
if (buf == NULL) |
| 62 |
return PyErr_NoMemory(); |
| 63 |
...Do some I/O operation involving buf... |
| 64 |
res = PyBytes_FromString(buf); |
| 65 |
free(buf); /* malloc'ed */ |
| 66 |
return res; |
| 67 |
|
| 68 |
In this example, the memory request for the I/O buffer is handled by the C |
| 69 |
library allocator. The Python memory manager is involved only in the allocation |
| 70 |
of the bytes object returned as a result. |
| 71 |
|
| 72 |
In most situations, however, it is recommended to allocate memory from the |
| 73 |
Python heap specifically because the latter is under control of the Python |
| 74 |
memory manager. For example, this is required when the interpreter is extended |
| 75 |
with new object types written in C. Another reason for using the Python heap is |
| 76 |
the desire to *inform* the Python memory manager about the memory needs of the |
| 77 |
extension module. Even when the requested memory is used exclusively for |
| 78 |
internal, highly specific purposes, delegating all memory requests to the Python |
| 79 |
memory manager causes the interpreter to have a more accurate image of its |
| 80 |
memory footprint as a whole. Consequently, under certain circumstances, the |
| 81 |
Python memory manager may or may not trigger appropriate actions, like garbage |
| 82 |
collection, memory compaction or other preventive procedures. Note that by using |
| 83 |
the C library allocator as shown in the previous example, the allocated memory |
| 84 |
for the I/O buffer escapes completely the Python memory manager. |
| 85 |
|
| 86 |
.. seealso:: |
| 87 |
|
| 88 |
The :envvar:`PYTHONMALLOC` environment variable can be used to configure |
| 89 |
the memory allocators used by Python. |
| 90 |
|
| 91 |
The :envvar:`PYTHONMALLOCSTATS` environment variable can be used to print |
| 92 |
statistics of the :ref:`pymalloc memory allocator <pymalloc>` every time a |
| 93 |
new pymalloc object arena is created, and on shutdown. |
| 94 |
|
| 95 |
Allocator Domains |
| 96 |
================= |
| 97 |
|
| 98 |
.. _allocator-domains: |
| 99 |
|
| 100 |
All allocating functions belong to one of three different "domains" (see also |
| 101 |
:c:type:`PyMemAllocatorDomain`). These domains represent different allocation |
| 102 |
strategies and are optimized for different purposes. The specific details on |
| 103 |
how every domain allocates memory or what internal functions each domain calls |
| 104 |
is considered an implementation detail, but for debugging purposes a simplified |
| 105 |
table can be found at :ref:`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`. |
| 108 |
|
| 109 |
The three allocation domains are: |
| 110 |
|
| 111 |
* Raw domain: intended for allocating memory for general-purpose memory |
| 112 |
buffers where the allocation *must* go to the system allocator or where the |
| 113 |
allocator can operate without an :term:`attached thread state`. The memory |
| 114 |
is requested directly from the system. See :ref:`Raw Memory Interface <raw-memoryinterface>`. |
| 115 |
|
| 116 |
* "Mem" domain: intended for allocating memory for Python buffers and |
| 117 |
general-purpose memory buffers where the allocation must be performed with |
| 118 |
an :term:`attached thread state`. The memory is taken from the Python private heap. |
| 119 |
See :ref:`Memory Interface <memoryinterface>`. |
| 120 |
|
| 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>`. |
| 123 |
|
| 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: |
| 137 |
|
| 138 |
Raw Memory Interface |
| 139 |
==================== |
| 140 |
|
| 141 |
The following function sets are wrappers to the system allocator. These |
| 142 |
functions are thread-safe, so a :term:`thread state` does not |
| 143 |
need to be :term:`attached <attached thread state>`. |
| 144 |
|
| 145 |
The :ref:`default raw memory allocator <default-memory-allocators>` uses |
| 146 |
the following functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` |
| 147 |
and :c:func:`!free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting |
| 148 |
zero bytes. |
| 149 |
|
| 150 |
.. versionadded:: 3.4 |
| 151 |
|
| 152 |
.. c:function:: void* PyMem_RawMalloc(size_t n) |
| 153 |
|
| 154 |
Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the |
| 155 |
allocated memory, or ``NULL`` if the request fails. |
| 156 |
|
| 157 |
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as |
| 158 |
if ``PyMem_RawMalloc(1)`` had been called instead. The memory will not have |
| 159 |
been initialized in any way. |
| 160 |
|
| 161 |
|
| 162 |
.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize) |
| 163 |
|
| 164 |
Allocates *nelem* elements each whose size in bytes is *elsize* and returns |
| 165 |
a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the |
| 166 |
request fails. The memory is initialized to zeros. |
| 167 |
|
| 168 |
Requesting zero elements or elements of size zero bytes returns a distinct |
| 169 |
non-``NULL`` pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been |
| 170 |
called instead. |
| 171 |
|
| 172 |
.. versionadded:: 3.5 |
| 173 |
|
| 174 |
|
| 175 |
.. c:function:: void* PyMem_RawRealloc(void *p, size_t n) |
| 176 |
|
| 177 |
Resizes the memory block pointed to by *p* to *n* bytes. The contents will |
| 178 |
be unchanged to the minimum of the old and the new sizes. |
| 179 |
|
| 180 |
If *p* is ``NULL``, the call is equivalent to ``PyMem_RawMalloc(n)``; else if |
| 181 |
*n* is equal to zero, the memory block is resized but is not freed, and the |
| 182 |
returned pointer is non-``NULL``. |
| 183 |
|
| 184 |
Unless *p* is ``NULL``, it must have been returned by a previous call to |
| 185 |
:c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or |
| 186 |
:c:func:`PyMem_RawCalloc`. |
| 187 |
|
| 188 |
If the request fails, :c:func:`PyMem_RawRealloc` returns ``NULL`` and *p* |
| 189 |
remains a valid pointer to the previous memory area. |
| 190 |
|
| 191 |
|
| 192 |
.. c:function:: void PyMem_RawFree(void *p) |
| 193 |
|
| 194 |
Frees the memory block pointed to by *p*, which must have been returned by a |
| 195 |
previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or |
| 196 |
:c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been |
| 197 |
called before, undefined behavior occurs. |
| 198 |
|
| 199 |
If *p* is ``NULL``, no operation is performed. |
| 200 |
|
| 201 |
|
| 202 |
.. _memoryinterface: |
| 203 |
|
| 204 |
Memory Interface |
| 205 |
================ |
| 206 |
|
| 207 |
The following function sets, modeled after the ANSI C standard, but specifying |
| 208 |
behavior when requesting zero bytes, are available for allocating and releasing |
| 209 |
memory from the Python heap. |
| 210 |
|
| 211 |
In the GIL-enabled build (default build) the |
| 212 |
:ref:`default memory allocator <default-memory-allocators>` uses the |
| 213 |
:ref:`pymalloc memory allocator <pymalloc>`, whereas in the |
| 214 |
:term:`free-threaded build`, the default is the |
| 215 |
:ref:`mimalloc memory allocator <mimalloc>` instead. |
| 216 |
|
| 217 |
.. warning:: |
| 218 |
|
| 219 |
There must be an :term:`attached thread state` when using these functions. |
| 220 |
|
| 221 |
.. versionchanged:: 3.6 |
| 222 |
|
| 223 |
The default allocator is now pymalloc instead of system :c:func:`malloc`. |
| 224 |
|
| 225 |
.. versionchanged:: 3.13 |
| 226 |
|
| 227 |
In the :term:`free-threaded <free threading>` build, the default allocator |
| 228 |
is now :ref:`mimalloc <mimalloc>`. |
| 229 |
|
| 230 |
.. c:function:: void* PyMem_Malloc(size_t n) |
| 231 |
|
| 232 |
Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the |
| 233 |
allocated memory, or ``NULL`` if the request fails. |
| 234 |
|
| 235 |
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as |
| 236 |
if ``PyMem_Malloc(1)`` had been called instead. The memory will not have |
| 237 |
been initialized in any way. |
| 238 |
|
| 239 |
|
| 240 |
.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize) |
| 241 |
|
| 242 |
Allocates *nelem* elements each whose size in bytes is *elsize* and returns |
| 243 |
a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the |
| 244 |
request fails. The memory is initialized to zeros. |
| 245 |
|
| 246 |
Requesting zero elements or elements of size zero bytes returns a distinct |
| 247 |
non-``NULL`` pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been called |
| 248 |
instead. |
| 249 |
|
| 250 |
.. versionadded:: 3.5 |
| 251 |
|
| 252 |
|
| 253 |
.. c:function:: void* PyMem_Realloc(void *p, size_t n) |
| 254 |
|
| 255 |
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be |
| 256 |
unchanged to the minimum of the old and the new sizes. |
| 257 |
|
| 258 |
If *p* is ``NULL``, the call is equivalent to ``PyMem_Malloc(n)``; else if *n* |
| 259 |
is equal to zero, the memory block is resized but is not freed, and the |
| 260 |
returned pointer is non-``NULL``. |
| 261 |
|
| 262 |
Unless *p* is ``NULL``, it must have been returned by a previous call to |
| 263 |
:c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`. |
| 264 |
|
| 265 |
If the request fails, :c:func:`PyMem_Realloc` returns ``NULL`` and *p* remains |
| 266 |
a valid pointer to the previous memory area. |
| 267 |
|
| 268 |
|
| 269 |
.. c:function:: void PyMem_Free(void *p) |
| 270 |
|
| 271 |
Frees the memory block pointed to by *p*, which must have been returned by a |
| 272 |
previous call to :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or |
| 273 |
:c:func:`PyMem_Calloc`. Otherwise, or if ``PyMem_Free(p)`` has been called |
| 274 |
before, undefined behavior occurs. |
| 275 |
|
| 276 |
If *p* is ``NULL``, no operation is performed. |
| 277 |
|
| 278 |
The following type-oriented macros are provided for convenience. Note that |
| 279 |
*TYPE* refers to any C type. |
| 280 |
|
| 281 |
|
| 282 |
.. c:macro:: PyMem_New(TYPE, n) |
| 283 |
|
| 284 |
Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of |
| 285 |
memory. Returns a pointer cast to ``TYPE*``. The memory will not have |
| 286 |
been initialized in any way. |
| 287 |
|
| 288 |
|
| 289 |
.. c:macro:: PyMem_Resize(p, TYPE, n) |
| 290 |
|
| 291 |
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n * |
| 292 |
sizeof(TYPE))`` bytes. Returns a pointer cast to ``TYPE*``. On return, |
| 293 |
*p* will be a pointer to the new memory area, or ``NULL`` in the event of |
| 294 |
failure. |
| 295 |
|
| 296 |
This is a C preprocessor macro; *p* is always reassigned. Save the original |
| 297 |
value of *p* to avoid losing memory when handling errors. |
| 298 |
|
| 299 |
|
| 300 |
.. c:function:: void PyMem_Del(void *p) |
| 301 |
|
| 302 |
Same as :c:func:`PyMem_Free`. |
| 303 |
|
| 304 |
|
| 305 |
Deprecated aliases |
| 306 |
------------------ |
| 307 |
|
| 308 |
These are :term:`soft deprecated` aliases to existing functions and macros. |
| 309 |
They exist solely for backwards compatibility. |
| 310 |
|
| 311 |
.. list-table:: |
| 312 |
:widths: auto |
| 313 |
:header-rows: 1 |
| 314 |
|
| 315 |
* * Deprecated alias |
| 316 |
* Corresponding function or macro |
| 317 |
* * .. c:macro:: PyMem_MALLOC(size) |
| 318 |
* :c:func:`PyMem_Malloc` |
| 319 |
* * .. c:macro:: PyMem_NEW(type, size) |
| 320 |
* :c:macro:`PyMem_New` |
| 321 |
* * .. c:macro:: PyMem_REALLOC(ptr, size) |
| 322 |
* :c:func:`PyMem_Realloc` |
| 323 |
* * .. c:macro:: PyMem_RESIZE(ptr, type, size) |
| 324 |
* :c:macro:`PyMem_Resize` |
| 325 |
* * .. c:macro:: PyMem_FREE(ptr) |
| 326 |
* :c:func:`PyMem_Free` |
| 327 |
* * .. c:macro:: PyMem_DEL(ptr) |
| 328 |
* :c:func:`PyMem_Free` |
| 329 |
|
| 330 |
.. versionchanged:: 3.4 |
| 331 |
|
| 332 |
The macros are now aliases of the corresponding functions and macros. |
| 333 |
Previously, their behavior was the same, but their use did not necessarily |
| 334 |
preserve binary compatibility across Python versions. |
| 335 |
|
| 336 |
.. deprecated:: 2.0 |
| 337 |
|
| 338 |
|
| 339 |
.. _objectinterface: |
| 340 |
|
| 341 |
Object allocators |
| 342 |
================= |
| 343 |
|
| 344 |
The following function sets, modeled after the ANSI C standard, but specifying |
| 345 |
behavior when requesting zero bytes, are available for allocating and releasing |
| 346 |
memory from the Python heap. |
| 347 |
|
| 348 |
.. note:: |
| 349 |
There is no guarantee that the memory returned by these allocators can be |
| 350 |
successfully cast to a Python object when intercepting the allocating |
| 351 |
functions in this domain by the methods described in |
| 352 |
the :ref:`Customize Memory Allocators <customize-memory-allocators>` section. |
| 353 |
|
| 354 |
The :ref:`default object allocator <default-memory-allocators>` uses the |
| 355 |
:ref:`pymalloc memory allocator <pymalloc>`. In the |
| 356 |
:term:`free-threaded <free threading>` build, the default is the |
| 357 |
:ref:`mimalloc memory allocator <mimalloc>` instead. |
| 358 |
|
| 359 |
.. warning:: |
| 360 |
|
| 361 |
There must be an :term:`attached thread state` when using these functions. |
| 362 |
|
| 363 |
.. c:function:: void* PyObject_Malloc(size_t n) |
| 364 |
|
| 365 |
Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the |
| 366 |
allocated memory, or ``NULL`` if the request fails. |
| 367 |
|
| 368 |
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as |
| 369 |
if ``PyObject_Malloc(1)`` had been called instead. The memory will not have |
| 370 |
been initialized in any way. |
| 371 |
|
| 372 |
|
| 373 |
.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize) |
| 374 |
|
| 375 |
Allocates *nelem* elements each whose size in bytes is *elsize* and returns |
| 376 |
a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the |
| 377 |
request fails. The memory is initialized to zeros. |
| 378 |
|
| 379 |
Requesting zero elements or elements of size zero bytes returns a distinct |
| 380 |
non-``NULL`` pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called |
| 381 |
instead. |
| 382 |
|
| 383 |
.. versionadded:: 3.5 |
| 384 |
|
| 385 |
|
| 386 |
.. c:function:: void* PyObject_Realloc(void *p, size_t n) |
| 387 |
|
| 388 |
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be |
| 389 |
unchanged to the minimum of the old and the new sizes. |
| 390 |
|
| 391 |
If *p* is ``NULL``, the call is equivalent to ``PyObject_Malloc(n)``; else if *n* |
| 392 |
is equal to zero, the memory block is resized but is not freed, and the |
| 393 |
returned pointer is non-``NULL``. |
| 394 |
|
| 395 |
Unless *p* is ``NULL``, it must have been returned by a previous call to |
| 396 |
:c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`. |
| 397 |
|
| 398 |
If the request fails, :c:func:`PyObject_Realloc` returns ``NULL`` and *p* remains |
| 399 |
a valid pointer to the previous memory area. |
| 400 |
|
| 401 |
|
| 402 |
.. c:function:: void PyObject_Free(void *p) |
| 403 |
|
| 404 |
Frees the memory block pointed to by *p*, which must have been returned by a |
| 405 |
previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or |
| 406 |
:c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called |
| 407 |
before, undefined behavior occurs. |
| 408 |
|
| 409 |
If *p* is ``NULL``, no operation is performed. |
| 410 |
|
| 411 |
Do not call this directly to free an object's memory; call the type's |
| 412 |
:c:member:`~PyTypeObject.tp_free` slot instead. |
| 413 |
|
| 414 |
Do not use this for memory allocated by :c:macro:`PyObject_GC_New` or |
| 415 |
:c:macro:`PyObject_GC_NewVar`; use :c:func:`PyObject_GC_Del` instead. |
| 416 |
|
| 417 |
.. seealso:: |
| 418 |
|
| 419 |
* :c:func:`PyObject_GC_Del` is the equivalent of this function for memory |
| 420 |
allocated by types that support garbage collection. |
| 421 |
* :c:func:`PyObject_Malloc` |
| 422 |
* :c:func:`PyObject_Realloc` |
| 423 |
* :c:func:`PyObject_Calloc` |
| 424 |
* :c:macro:`PyObject_New` |
| 425 |
* :c:macro:`PyObject_NewVar` |
| 426 |
* :c:func:`PyType_GenericAlloc` |
| 427 |
* :c:member:`~PyTypeObject.tp_free` |
| 428 |
|
| 429 |
|
| 430 |
.. _default-memory-allocators: |
| 431 |
|
| 432 |
Default Memory Allocators |
| 433 |
========================= |
| 434 |
|
| 435 |
Default memory allocators: |
| 436 |
|
| 437 |
=================================== ======================= ==================== ====================== ====================== |
| 438 |
Configuration Name PyMem_RawMalloc PyMem_Malloc PyObject_Malloc |
| 439 |
=================================== ======================= ==================== ====================== ====================== |
| 440 |
Release build ``"pymalloc"`` ``malloc`` ``pymalloc`` ``pymalloc`` |
| 441 |
Debug build ``"pymalloc_debug"`` ``malloc`` + debug ``pymalloc`` + debug ``pymalloc`` + debug |
| 442 |
Release build, without pymalloc ``"malloc"`` ``malloc`` ``malloc`` ``malloc`` |
| 443 |
Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug ``malloc`` + debug ``malloc`` + debug |
| 444 |
Free-threaded build ``"mimalloc"`` ``mimalloc`` ``mimalloc`` ``mimalloc`` |
| 445 |
Free-threaded debug build ``"mimalloc_debug"`` ``mimalloc`` + debug ``mimalloc`` + debug ``mimalloc`` + debug |
| 446 |
=================================== ======================= ==================== ====================== ====================== |
| 447 |
|
| 448 |
Legend: |
| 449 |
|
| 450 |
* Name: value for :envvar:`PYTHONMALLOC` environment variable. |
| 451 |
* ``malloc``: system allocators from the standard C library, C functions: |
| 452 |
:c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. |
| 453 |
* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`. |
| 454 |
* ``mimalloc``: :ref:`mimalloc memory allocator <mimalloc>`. |
| 455 |
* "+ debug": with :ref:`debug hooks on the Python memory allocators |
| 456 |
<pymem-debug-hooks>`. |
| 457 |
* "Debug build": :ref:`Python build in debug mode <debug-build>`. |
| 458 |
|
| 459 |
.. _customize-memory-allocators: |
| 460 |
|
| 461 |
Customize Memory Allocators |
| 462 |
=========================== |
| 463 |
|
| 464 |
.. versionadded:: 3.4 |
| 465 |
|
| 466 |
.. c:type:: PyMemAllocatorEx |
| 467 |
|
| 468 |
Structure used to describe a memory block allocator. The structure has |
| 469 |
the following fields: |
| 470 |
|
| 471 |
+----------------------------------------------------------+---------------------------------------+ |
| 472 |
| Field | Meaning | |
| 473 |
+==========================================================+=======================================+ |
| 474 |
| ``void *ctx`` | user context passed as first argument | |
| 475 |
+----------------------------------------------------------+---------------------------------------+ |
| 476 |
| ``void* malloc(void *ctx, size_t size)`` | allocate a memory block | |
| 477 |
+----------------------------------------------------------+---------------------------------------+ |
| 478 |
| ``void* calloc(void *ctx, size_t nelem, size_t elsize)`` | allocate a memory block initialized | |
| 479 |
| | with zeros | |
| 480 |
+----------------------------------------------------------+---------------------------------------+ |
| 481 |
| ``void* realloc(void *ctx, void *ptr, size_t new_size)`` | allocate or resize a memory block | |
| 482 |
+----------------------------------------------------------+---------------------------------------+ |
| 483 |
| ``void free(void *ctx, void *ptr)`` | free a memory block | |
| 484 |
+----------------------------------------------------------+---------------------------------------+ |
| 485 |
|
| 486 |
.. versionchanged:: 3.5 |
| 487 |
The :c:type:`!PyMemAllocator` structure was renamed to |
| 488 |
:c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added. |
| 489 |
|
| 490 |
|
| 491 |
.. c:type:: PyMemAllocatorDomain |
| 492 |
|
| 493 |
Enum used to identify an allocator domain. Domains: |
| 494 |
|
| 495 |
.. c:namespace:: NULL |
| 496 |
|
| 497 |
.. c:macro:: PYMEM_DOMAIN_RAW |
| 498 |
|
| 499 |
Functions: |
| 500 |
|
| 501 |
* :c:func:`PyMem_RawMalloc` |
| 502 |
* :c:func:`PyMem_RawRealloc` |
| 503 |
* :c:func:`PyMem_RawCalloc` |
| 504 |
* :c:func:`PyMem_RawFree` |
| 505 |
|
| 506 |
.. c:macro:: PYMEM_DOMAIN_MEM |
| 507 |
|
| 508 |
Functions: |
| 509 |
|
| 510 |
* :c:func:`PyMem_Malloc`, |
| 511 |
* :c:func:`PyMem_Realloc` |
| 512 |
* :c:func:`PyMem_Calloc` |
| 513 |
* :c:func:`PyMem_Free` |
| 514 |
|
| 515 |
.. c:macro:: PYMEM_DOMAIN_OBJ |
| 516 |
|
| 517 |
Functions: |
| 518 |
|
| 519 |
* :c:func:`PyObject_Malloc` |
| 520 |
* :c:func:`PyObject_Realloc` |
| 521 |
* :c:func:`PyObject_Calloc` |
| 522 |
* :c:func:`PyObject_Free` |
| 523 |
|
| 524 |
.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator) |
| 525 |
|
| 526 |
Get the memory block allocator of the specified domain. |
| 527 |
|
| 528 |
|
| 529 |
.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator) |
| 530 |
|
| 531 |
Set the memory block allocator of the specified domain. |
| 532 |
|
| 533 |
The new allocator must return a distinct non-``NULL`` pointer when requesting |
| 534 |
zero bytes. |
| 535 |
|
| 536 |
For the :c:macro:`PYMEM_DOMAIN_RAW` domain, the allocator must be |
| 537 |
thread-safe: a :term:`thread state` is not :term:`attached <attached thread state>` |
| 538 |
when the allocator is called. |
| 539 |
|
| 540 |
For the remaining domains, the allocator must also be thread-safe: |
| 541 |
the allocator may be called in different interpreters that do not |
| 542 |
share a :term:`GIL`. |
| 543 |
|
| 544 |
If the new allocator is not a hook (does not call the previous allocator), |
| 545 |
the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the |
| 546 |
debug hooks on top on the new allocator. |
| 547 |
|
| 548 |
See also :c:member:`PyPreConfig.allocator` and :ref:`Preinitialize Python |
| 549 |
with PyPreConfig <c-preinit>`. |
| 550 |
|
| 551 |
.. warning:: |
| 552 |
|
| 553 |
:c:func:`PyMem_SetAllocator` does have the following contract: |
| 554 |
|
| 555 |
* It can be called after :c:func:`Py_PreInitialize` and before |
| 556 |
:c:func:`Py_InitializeFromConfig` to install a custom memory |
| 557 |
allocator. There are no restrictions over the installed allocator |
| 558 |
other than the ones imposed by the domain (for instance, the Raw |
| 559 |
Domain allows the allocator to be called without an :term:`attached thread state`). |
| 560 |
See :ref:`the section on allocator domains <allocator-domains>` for more |
| 561 |
information. |
| 562 |
|
| 563 |
* If called after Python has finish initializing (after |
| 564 |
:c:func:`Py_InitializeFromConfig` has been called) the allocator |
| 565 |
**must** wrap the existing allocator. Substituting the current |
| 566 |
allocator for some other arbitrary one is **not supported**. |
| 567 |
|
| 568 |
.. versionchanged:: 3.12 |
| 569 |
All allocators must be thread-safe. |
| 570 |
|
| 571 |
|
| 572 |
.. c:function:: void PyMem_SetupDebugHooks(void) |
| 573 |
|
| 574 |
Setup :ref:`debug hooks in the Python memory allocators <pymem-debug-hooks>` |
| 575 |
to detect memory errors. |
| 576 |
|
| 577 |
|
| 578 |
.. _pymem-debug-hooks: |
| 579 |
|
| 580 |
Debug hooks on the Python memory allocators |
| 581 |
=========================================== |
| 582 |
|
| 583 |
When :ref:`Python is built in debug mode <debug-build>`, the |
| 584 |
:c:func:`PyMem_SetupDebugHooks` function is called at the :ref:`Python |
| 585 |
preinitialization <c-preinit>` to setup debug hooks on Python memory allocators |
| 586 |
to detect memory errors. |
| 587 |
|
| 588 |
The :envvar:`PYTHONMALLOC` environment variable can be used to install debug |
| 589 |
hooks on a Python compiled in release mode (ex: ``PYTHONMALLOC=debug``). |
| 590 |
|
| 591 |
The :c:func:`PyMem_SetupDebugHooks` function can be used to set debug hooks |
| 592 |
after calling :c:func:`PyMem_SetAllocator`. |
| 593 |
|
| 594 |
These debug hooks fill dynamically allocated memory blocks with special, |
| 595 |
recognizable bit patterns. Newly allocated memory is filled with the byte |
| 596 |
``0xCD`` (``PYMEM_CLEANBYTE``), freed memory is filled with the byte ``0xDD`` |
| 597 |
(``PYMEM_DEADBYTE``). Memory blocks are surrounded by "forbidden bytes" |
| 598 |
filled with the byte ``0xFD`` (``PYMEM_FORBIDDENBYTE``). Strings of these bytes |
| 599 |
are unlikely to be valid addresses, floats, or ASCII strings. |
| 600 |
|
| 601 |
Runtime checks: |
| 602 |
|
| 603 |
- Detect API violations. For example, detect if :c:func:`PyObject_Free` is |
| 604 |
called on a memory block allocated by :c:func:`PyMem_Malloc`. |
| 605 |
- Detect write before the start of the buffer (buffer underflow). |
| 606 |
- Detect write after the end of the buffer (buffer overflow). |
| 607 |
- Check that there is an :term:`attached thread state` when |
| 608 |
allocator functions of :c:macro:`PYMEM_DOMAIN_OBJ` (ex: |
| 609 |
:c:func:`PyObject_Malloc`) and :c:macro:`PYMEM_DOMAIN_MEM` (ex: |
| 610 |
:c:func:`PyMem_Malloc`) domains are called. |
| 611 |
|
| 612 |
On error, the debug hooks use the :mod:`tracemalloc` module to get the |
| 613 |
traceback where a memory block was allocated. The traceback is only displayed |
| 614 |
if :mod:`tracemalloc` is tracing Python memory allocations and the memory block |
| 615 |
was traced. |
| 616 |
|
| 617 |
Let *S* = ``sizeof(size_t)``. ``2*S`` bytes are added at each end of each block |
| 618 |
of *N* bytes requested. The memory layout is like so, where p represents the |
| 619 |
address returned by a malloc-like or realloc-like function (``p[i:j]`` means |
| 620 |
the slice of bytes from ``*(p+i)`` inclusive up to ``*(p+j)`` exclusive; note |
| 621 |
that the treatment of negative indices differs from a Python slice): |
| 622 |
|
| 623 |
``p[-2*S:-S]`` |
| 624 |
Number of bytes originally asked for. This is a size_t, big-endian (easier |
| 625 |
to read in a memory dump). |
| 626 |
``p[-S]`` |
| 627 |
API identifier (ASCII character): |
| 628 |
|
| 629 |
* ``'r'`` for :c:macro:`PYMEM_DOMAIN_RAW`. |
| 630 |
* ``'m'`` for :c:macro:`PYMEM_DOMAIN_MEM`. |
| 631 |
* ``'o'`` for :c:macro:`PYMEM_DOMAIN_OBJ`. |
| 632 |
|
| 633 |
``p[-S+1:0]`` |
| 634 |
Copies of PYMEM_FORBIDDENBYTE. Used to catch under- writes and reads. |
| 635 |
|
| 636 |
``p[0:N]`` |
| 637 |
The requested memory, filled with copies of PYMEM_CLEANBYTE, used to catch |
| 638 |
reference to uninitialized memory. When a realloc-like function is called |
| 639 |
requesting a larger memory block, the new excess bytes are also filled with |
| 640 |
PYMEM_CLEANBYTE. When a free-like function is called, these are |
| 641 |
overwritten with PYMEM_DEADBYTE, to catch reference to freed memory. When |
| 642 |
a realloc- like function is called requesting a smaller memory block, the |
| 643 |
excess old bytes are also filled with PYMEM_DEADBYTE. |
| 644 |
|
| 645 |
``p[N:N+S]`` |
| 646 |
Copies of PYMEM_FORBIDDENBYTE. Used to catch over- writes and reads. |
| 647 |
|
| 648 |
``p[N+S:N+2*S]`` |
| 649 |
Only used if the ``PYMEM_DEBUG_SERIALNO`` macro is defined (not defined by |
| 650 |
default). |
| 651 |
|
| 652 |
A serial number, incremented by 1 on each call to a malloc-like or |
| 653 |
realloc-like function. Big-endian :c:type:`size_t`. If "bad memory" is detected |
| 654 |
later, the serial number gives an excellent way to set a breakpoint on the |
| 655 |
next run, to capture the instant at which this block was passed out. The |
| 656 |
static function bumpserialno() in obmalloc.c is the only place the serial |
| 657 |
number is incremented, and exists so you can set such a breakpoint easily. |
| 658 |
|
| 659 |
A realloc-like or free-like function first checks that the PYMEM_FORBIDDENBYTE |
| 660 |
bytes at each end are intact. If they've been altered, diagnostic output is |
| 661 |
written to stderr, and the program is aborted via Py_FatalError(). The other |
| 662 |
main failure mode is provoking a memory error when a program reads up one of |
| 663 |
the special bit patterns and tries to use it as an address. If you get in a |
| 664 |
debugger then and look at the object, you're likely to see that it's entirely |
| 665 |
filled with PYMEM_DEADBYTE (meaning freed memory is getting used) or |
| 666 |
PYMEM_CLEANBYTE (meaning uninitialized memory is getting used). |
| 667 |
|
| 668 |
.. versionchanged:: 3.6 |
| 669 |
The :c:func:`PyMem_SetupDebugHooks` function now also works on Python |
| 670 |
compiled in release mode. On error, the debug hooks now use |
| 671 |
:mod:`tracemalloc` to get the traceback where a memory block was allocated. |
| 672 |
The debug hooks now also check if there is an :term:`attached thread state` when |
| 673 |
functions of :c:macro:`PYMEM_DOMAIN_OBJ` and :c:macro:`PYMEM_DOMAIN_MEM` domains are |
| 674 |
called. |
| 675 |
|
| 676 |
.. versionchanged:: 3.8 |
| 677 |
Byte patterns ``0xCB`` (``PYMEM_CLEANBYTE``), ``0xDB`` (``PYMEM_DEADBYTE``) |
| 678 |
and ``0xFB`` (``PYMEM_FORBIDDENBYTE``) have been replaced with ``0xCD``, |
| 679 |
``0xDD`` and ``0xFD`` to use the same values than Windows CRT debug |
| 680 |
``malloc()`` and ``free()``. |
| 681 |
|
| 682 |
|
| 683 |
.. _pymalloc: |
| 684 |
|
| 685 |
The pymalloc allocator |
| 686 |
====================== |
| 687 |
|
| 688 |
Python has a *pymalloc* allocator optimized for small objects (smaller or equal |
| 689 |
to 512 bytes) with a short lifetime. It uses memory mappings called "arenas" |
| 690 |
with a fixed size of either 256 KiB on 32-bit platforms or 1 MiB on 64-bit |
| 691 |
platforms. It falls back to :c:func:`PyMem_RawMalloc` and |
| 692 |
:c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes. |
| 693 |
|
| 694 |
*pymalloc* is the :ref:`default allocator <default-memory-allocators>` of the |
| 695 |
:c:macro:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and |
| 696 |
:c:macro:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains. |
| 697 |
|
| 698 |
The arena allocator uses the following functions: |
| 699 |
|
| 700 |
* :c:func:`!VirtualAlloc` and :c:func:`!VirtualFree` on Windows, |
| 701 |
* :c:func:`!mmap` and :c:func:`!munmap` if available, |
| 702 |
* :c:func:`malloc` and :c:func:`free` otherwise. |
| 703 |
|
| 704 |
This allocator is disabled if Python is configured with the |
| 705 |
:option:`--without-pymalloc` option. It can also be disabled at runtime using |
| 706 |
the :envvar:`PYTHONMALLOC` environment variable (ex: ``PYTHONMALLOC=malloc``). |
| 707 |
|
| 708 |
Typically, it makes sense to disable the pymalloc allocator when building |
| 709 |
Python with AddressSanitizer (:option:`--with-address-sanitizer`) which helps |
| 710 |
uncover low level bugs within the C code. |
| 711 |
|
| 712 |
Customize pymalloc Arena Allocator |
| 713 |
---------------------------------- |
| 714 |
|
| 715 |
.. versionadded:: 3.4 |
| 716 |
|
| 717 |
.. c:type:: PyObjectArenaAllocator |
| 718 |
|
| 719 |
Structure used to describe an arena allocator. The structure has |
| 720 |
three fields: |
| 721 |
|
| 722 |
+--------------------------------------------------+---------------------------------------+ |
| 723 |
| Field | Meaning | |
| 724 |
+==================================================+=======================================+ |
| 725 |
| ``void *ctx`` | user context passed as first argument | |
| 726 |
+--------------------------------------------------+---------------------------------------+ |
| 727 |
| ``void* alloc(void *ctx, size_t size)`` | allocate an arena of size bytes | |
| 728 |
+--------------------------------------------------+---------------------------------------+ |
| 729 |
| ``void free(void *ctx, void *ptr, size_t size)`` | free an arena | |
| 730 |
+--------------------------------------------------+---------------------------------------+ |
| 731 |
|
| 732 |
.. c:function:: void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator) |
| 733 |
|
| 734 |
Get the arena allocator. |
| 735 |
|
| 736 |
.. c:function:: void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator) |
| 737 |
|
| 738 |
Set the arena allocator. |
| 739 |
|
| 740 |
.. _mimalloc: |
| 741 |
|
| 742 |
The mimalloc allocator |
| 743 |
====================== |
| 744 |
|
| 745 |
.. versionadded:: 3.13 |
| 746 |
|
| 747 |
Python supports the `mimalloc <https://github.com/microsoft/mimalloc/>`__ |
| 748 |
allocator when the underlying platform support is available. |
| 749 |
mimalloc is a general purpose allocator with excellent performance |
| 750 |
characteristics, initially developed by Daan Leijen for the runtime systems |
| 751 |
of the Koka and Lean languages. |
| 752 |
|
| 753 |
Unlike :ref:`pymalloc <pymalloc>`, which is optimized for small objects (512 |
| 754 |
bytes or fewer), mimalloc handles allocations of any size. |
| 755 |
|
| 756 |
In the :term:`free-threaded <free threading>` build, mimalloc is the default |
| 757 |
and **required** allocator for the :c:macro:`PYMEM_DOMAIN_MEM` and |
| 758 |
:c:macro:`PYMEM_DOMAIN_OBJ` domains. It cannot be disabled in free-threaded |
| 759 |
builds. The free-threaded build uses per-thread mimalloc heaps, which allows |
| 760 |
allocation and deallocation to proceed without locking in most cases. |
| 761 |
|
| 762 |
In the default (non-free-threaded) build, mimalloc is available but not the |
| 763 |
default allocator. It can be selected at runtime using |
| 764 |
:envvar:`PYTHONMALLOC`\ ``=mimalloc`` (or ``mimalloc_debug`` to include |
| 765 |
:ref:`debug hooks <pymem-debug-hooks>`). It can be disabled at build time |
| 766 |
using the :option:`--without-mimalloc` configure option, but this option |
| 767 |
cannot be combined with :option:`--disable-gil`. |
| 768 |
|
| 769 |
tracemalloc C API |
| 770 |
================= |
| 771 |
|
| 772 |
.. versionadded:: 3.7 |
| 773 |
|
| 774 |
.. c:function:: int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size) |
| 775 |
|
| 776 |
Track an allocated memory block in the :mod:`tracemalloc` module. |
| 777 |
|
| 778 |
Return ``0`` on success, return ``-1`` on error (failed to allocate memory to |
| 779 |
store the trace). Return ``-2`` if tracemalloc is disabled. |
| 780 |
|
| 781 |
If memory block is already tracked, update the existing trace. |
| 782 |
|
| 783 |
.. c:function:: int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr) |
| 784 |
|
| 785 |
Untrack an allocated memory block in the :mod:`tracemalloc` module. |
| 786 |
Do nothing if the block was not tracked. |
| 787 |
|
| 788 |
Return ``-2`` if tracemalloc is disabled, otherwise return ``0``. |
| 789 |
|
| 790 |
|
| 791 |
.. _memoryexamples: |
| 792 |
|
| 793 |
Examples |
| 794 |
======== |
| 795 |
|
| 796 |
Here is the example from section :ref:`memoryoverview`, rewritten so that the |
| 797 |
I/O buffer is allocated from the Python heap by using the first function set:: |
| 798 |
|
| 799 |
PyObject *res; |
| 800 |
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */ |
| 801 |
|
| 802 |
if (buf == NULL) |
| 803 |
return PyErr_NoMemory(); |
| 804 |
/* ...Do some I/O operation involving buf... */ |
| 805 |
res = PyBytes_FromString(buf); |
| 806 |
PyMem_Free(buf); /* allocated with PyMem_Malloc */ |
| 807 |
return res; |
| 808 |
|
| 809 |
The same code using the type-oriented function set:: |
| 810 |
|
| 811 |
PyObject *res; |
| 812 |
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */ |
| 813 |
|
| 814 |
if (buf == NULL) |
| 815 |
return PyErr_NoMemory(); |
| 816 |
/* ...Do some I/O operation involving buf... */ |
| 817 |
res = PyBytes_FromString(buf); |
| 818 |
PyMem_Free(buf); /* allocated with PyMem_New */ |
| 819 |
return res; |
| 820 |
|
| 821 |
Note that in the two examples above, the buffer is always manipulated via |
| 822 |
functions belonging to the same set. Indeed, it is required to use the same |
| 823 |
memory API family for a given memory block, so that the risk of mixing different |
| 824 |
allocators is reduced to a minimum. The following code sequence contains two |
| 825 |
errors, one of which is labeled as *fatal* because it mixes two different |
| 826 |
allocators operating on different heaps. :: |
| 827 |
|
| 828 |
char *buf1 = PyMem_New(char, BUFSIZ); |
| 829 |
char *buf2 = (char *) malloc(BUFSIZ); |
| 830 |
char *buf3 = (char *) PyMem_Malloc(BUFSIZ); |
| 831 |
... |
| 832 |
PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */ |
| 833 |
free(buf2); /* Right -- allocated via malloc() */ |
| 834 |
free(buf1); /* Fatal -- should be PyMem_Free() */ |
| 835 |
|
| 836 |
In addition to the functions aimed at handling raw memory blocks from the Python |
| 837 |
heap, objects in Python are allocated and released with :c:macro:`PyObject_New`, |
| 838 |
:c:macro:`PyObject_NewVar` and :c:func:`PyObject_Free`. |
| 839 |
|
| 840 |
These will be explained in the next chapter on defining and implementing new |
| 841 |
object types in C. |