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