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() 45 single: calloc() 46 single: realloc() 47 single: free() 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 98All allocating functions belong to one of three different "domains" (see also 99:c:type:`PyMemAllocatorDomain`). These domains represent different allocation 100strategies and are optimized for different purposes. The specific details on 101how every domain allocates memory or what internal functions each domain calls 102is considered an implementation detail, but for debugging purposes a simplified 103table can be found at :ref:`here <default-memory-allocators>`. There is no hard 104requirement to use the memory returned by the allocation functions belonging to 105a given domain for only the purposes hinted by that domain (although this is the 106recommended practice). For example, one could use the memory returned by 107:c:func:`PyMem_RawMalloc` for allocating Python objects or the memory returned 108by :c:func:`PyObject_Malloc` for allocating memory for buffers. 109 110The three allocation domains are: 111 112* Raw domain: intended for allocating memory for general-purpose memory 113 buffers where the allocation *must* go to the system allocator or where the 114 allocator can operate without the :term:`GIL`. The memory is requested directly 115 to the system. 116 117* "Mem" domain: intended for allocating memory for Python buffers and 118 general-purpose memory buffers where the allocation must be performed with 119 the :term:`GIL` held. The memory is taken from the Python private heap. 120 121* Object domain: intended for allocating memory belonging to Python objects. The 122 memory is taken from the Python private heap. 123 124When freeing memory previously allocated by the allocating functions belonging to a 125given domain,the matching specific deallocating functions must be used. For example, 126:c:func:`PyMem_Free` must be used to free memory allocated using :c:func:`PyMem_Malloc`. 127 128Raw Memory Interface 129==================== 130 131The following function sets are wrappers to the system allocator. These 132functions are thread-safe, the :term:`GIL <global interpreter lock>` does not 133need to be held. 134 135The :ref:`default raw memory allocator <default-memory-allocators>` uses 136the following functions: :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` 137and :c:func:`free`; call ``malloc(1)`` (or ``calloc(1, 1)``) when requesting 138zero bytes. 139 140.. versionadded:: 3.4 141 142.. c:function:: void* PyMem_RawMalloc(size_t n) 143 144 Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the 145 allocated memory, or ``NULL`` if the request fails. 146 147 Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as 148 if ``PyMem_RawMalloc(1)`` had been called instead. The memory will not have 149 been initialized in any way. 150 151 152.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize) 153 154 Allocates *nelem* elements each whose size in bytes is *elsize* and returns 155 a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the 156 request fails. The memory is initialized to zeros. 157 158 Requesting zero elements or elements of size zero bytes returns a distinct 159 non-``NULL`` pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been 160 called instead. 161 162 .. versionadded:: 3.5 163 164 165.. c:function:: void* PyMem_RawRealloc(void *p, size_t n) 166 167 Resizes the memory block pointed to by *p* to *n* bytes. The contents will 168 be unchanged to the minimum of the old and the new sizes. 169 170 If *p* is ``NULL``, the call is equivalent to ``PyMem_RawMalloc(n)``; else if 171 *n* is equal to zero, the memory block is resized but is not freed, and the 172 returned pointer is non-``NULL``. 173 174 Unless *p* is ``NULL``, it must have been returned by a previous call to 175 :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or 176 :c:func:`PyMem_RawCalloc`. 177 178 If the request fails, :c:func:`PyMem_RawRealloc` returns ``NULL`` and *p* 179 remains a valid pointer to the previous memory area. 180 181 182.. c:function:: void PyMem_RawFree(void *p) 183 184 Frees the memory block pointed to by *p*, which must have been returned by a 185 previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or 186 :c:func:`PyMem_RawCalloc`. Otherwise, or if ``PyMem_RawFree(p)`` has been 187 called before, undefined behavior occurs. 188 189 If *p* is ``NULL``, no operation is performed. 190 191 192.. _memoryinterface: 193 194Memory Interface 195================ 196 197The following function sets, modeled after the ANSI C standard, but specifying 198behavior when requesting zero bytes, are available for allocating and releasing 199memory from the Python heap. 200 201The :ref:`default memory allocator <default-memory-allocators>` uses the 202:ref:`pymalloc memory allocator <pymalloc>`. 203 204.. warning:: 205 206 The :term:`GIL <global interpreter lock>` must be held when using these 207 functions. 208 209.. versionchanged:: 3.6 210 211 The default allocator is now pymalloc instead of system :c:func:`malloc`. 212 213.. c:function:: void* PyMem_Malloc(size_t n) 214 215 Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the 216 allocated memory, or ``NULL`` if the request fails. 217 218 Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as 219 if ``PyMem_Malloc(1)`` had been called instead. The memory will not have 220 been initialized in any way. 221 222 223.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize) 224 225 Allocates *nelem* elements each whose size in bytes is *elsize* and returns 226 a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the 227 request fails. The memory is initialized to zeros. 228 229 Requesting zero elements or elements of size zero bytes returns a distinct 230 non-``NULL`` pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been called 231 instead. 232 233 .. versionadded:: 3.5 234 235 236.. c:function:: void* PyMem_Realloc(void *p, size_t n) 237 238 Resizes the memory block pointed to by *p* to *n* bytes. The contents will be 239 unchanged to the minimum of the old and the new sizes. 240 241 If *p* is ``NULL``, the call is equivalent to ``PyMem_Malloc(n)``; else if *n* 242 is equal to zero, the memory block is resized but is not freed, and the 243 returned pointer is non-``NULL``. 244 245 Unless *p* is ``NULL``, it must have been returned by a previous call to 246 :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`. 247 248 If the request fails, :c:func:`PyMem_Realloc` returns ``NULL`` and *p* remains 249 a valid pointer to the previous memory area. 250 251 252.. c:function:: void PyMem_Free(void *p) 253 254 Frees the memory block pointed to by *p*, which must have been returned by a 255 previous call to :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or 256 :c:func:`PyMem_Calloc`. Otherwise, or if ``PyMem_Free(p)`` has been called 257 before, undefined behavior occurs. 258 259 If *p* is ``NULL``, no operation is performed. 260 261The following type-oriented macros are provided for convenience. Note that 262*TYPE* refers to any C type. 263 264 265.. c:function:: TYPE* PyMem_New(TYPE, size_t n) 266 267 Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of 268 memory. Returns a pointer cast to :c:type:`TYPE*`. The memory will not have 269 been initialized in any way. 270 271 272.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n) 273 274 Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n * 275 sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE*`. On return, 276 *p* will be a pointer to the new memory area, or ``NULL`` in the event of 277 failure. 278 279 This is a C preprocessor macro; *p* is always reassigned. Save the original 280 value of *p* to avoid losing memory when handling errors. 281 282 283.. c:function:: void PyMem_Del(void *p) 284 285 Same as :c:func:`PyMem_Free`. 286 287In addition, the following macro sets are provided for calling the Python memory 288allocator directly, without involving the C API functions listed above. However, 289note that their use does not preserve binary compatibility across Python 290versions and is therefore deprecated in extension modules. 291 292* ``PyMem_MALLOC(size)`` 293* ``PyMem_NEW(type, size)`` 294* ``PyMem_REALLOC(ptr, size)`` 295* ``PyMem_RESIZE(ptr, type, size)`` 296* ``PyMem_FREE(ptr)`` 297* ``PyMem_DEL(ptr)`` 298 299 300Object allocators 301================= 302 303The following function sets, modeled after the ANSI C standard, but specifying 304behavior when requesting zero bytes, are available for allocating and releasing 305memory from the Python heap. 306 307.. note:: 308 There is no guarantee that the memory returned by these allocators can be 309 successfully casted to a Python object when intercepting the allocating 310 functions in this domain by the methods described in 311 the :ref:`Customize Memory Allocators <customize-memory-allocators>` section. 312 313The :ref:`default object allocator <default-memory-allocators>` uses the 314:ref:`pymalloc memory allocator <pymalloc>`. 315 316.. warning:: 317 318 The :term:`GIL <global interpreter lock>` must be held when using these 319 functions. 320 321.. c:function:: void* PyObject_Malloc(size_t n) 322 323 Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the 324 allocated memory, or ``NULL`` if the request fails. 325 326 Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as 327 if ``PyObject_Malloc(1)`` had been called instead. The memory will not have 328 been initialized in any way. 329 330 331.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize) 332 333 Allocates *nelem* elements each whose size in bytes is *elsize* and returns 334 a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the 335 request fails. The memory is initialized to zeros. 336 337 Requesting zero elements or elements of size zero bytes returns a distinct 338 non-``NULL`` pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called 339 instead. 340 341 .. versionadded:: 3.5 342 343 344.. c:function:: void* PyObject_Realloc(void *p, size_t n) 345 346 Resizes the memory block pointed to by *p* to *n* bytes. The contents will be 347 unchanged to the minimum of the old and the new sizes. 348 349 If *p* is ``NULL``, the call is equivalent to ``PyObject_Malloc(n)``; else if *n* 350 is equal to zero, the memory block is resized but is not freed, and the 351 returned pointer is non-``NULL``. 352 353 Unless *p* is ``NULL``, it must have been returned by a previous call to 354 :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`. 355 356 If the request fails, :c:func:`PyObject_Realloc` returns ``NULL`` and *p* remains 357 a valid pointer to the previous memory area. 358 359 360.. c:function:: void PyObject_Free(void *p) 361 362 Frees the memory block pointed to by *p*, which must have been returned by a 363 previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or 364 :c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called 365 before, undefined behavior occurs. 366 367 If *p* is ``NULL``, no operation is performed. 368 369 370.. _default-memory-allocators: 371 372Default Memory Allocators 373========================= 374 375Default memory allocators: 376 377=============================== ==================== ================== ===================== ==================== 378Configuration Name PyMem_RawMalloc PyMem_Malloc PyObject_Malloc 379=============================== ==================== ================== ===================== ==================== 380Release build ``"pymalloc"`` ``malloc`` ``pymalloc`` ``pymalloc`` 381Debug build ``"pymalloc_debug"`` ``malloc`` + debug ``pymalloc`` + debug ``pymalloc`` + debug 382Release build, without pymalloc ``"malloc"`` ``malloc`` ``malloc`` ``malloc`` 383Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug ``malloc`` + debug ``malloc`` + debug 384=============================== ==================== ================== ===================== ==================== 385 386Legend: 387 388* Name: value for :envvar:`PYTHONMALLOC` environment variable. 389* ``malloc``: system allocators from the standard C library, C functions: 390 :c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. 391* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`. 392* "+ debug": with :ref:`debug hooks on the Python memory allocators 393 <pymem-debug-hooks>`. 394* "Debug build": :ref:`Python build in debug mode <debug-build>`. 395 396.. _customize-memory-allocators: 397 398Customize Memory Allocators 399=========================== 400 401.. versionadded:: 3.4 402 403.. c:type:: PyMemAllocatorEx 404 405 Structure used to describe a memory block allocator. The structure has 406 four fields: 407 408 +----------------------------------------------------------+---------------------------------------+ 409 | Field | Meaning | 410 +==========================================================+=======================================+ 411 | ``void *ctx`` | user context passed as first argument | 412 +----------------------------------------------------------+---------------------------------------+ 413 | ``void* malloc(void *ctx, size_t size)`` | allocate a memory block | 414 +----------------------------------------------------------+---------------------------------------+ 415 | ``void* calloc(void *ctx, size_t nelem, size_t elsize)`` | allocate a memory block initialized | 416 | | with zeros | 417 +----------------------------------------------------------+---------------------------------------+ 418 | ``void* realloc(void *ctx, void *ptr, size_t new_size)`` | allocate or resize a memory block | 419 +----------------------------------------------------------+---------------------------------------+ 420 | ``void free(void *ctx, void *ptr)`` | free a memory block | 421 +----------------------------------------------------------+---------------------------------------+ 422 423 .. versionchanged:: 3.5 424 The :c:type:`PyMemAllocator` structure was renamed to 425 :c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added. 426 427 428.. c:type:: PyMemAllocatorDomain 429 430 Enum used to identify an allocator domain. Domains: 431 432 .. c:macro:: PYMEM_DOMAIN_RAW 433 434 Functions: 435 436 * :c:func:`PyMem_RawMalloc` 437 * :c:func:`PyMem_RawRealloc` 438 * :c:func:`PyMem_RawCalloc` 439 * :c:func:`PyMem_RawFree` 440 441 .. c:macro:: PYMEM_DOMAIN_MEM 442 443 Functions: 444 445 * :c:func:`PyMem_Malloc`, 446 * :c:func:`PyMem_Realloc` 447 * :c:func:`PyMem_Calloc` 448 * :c:func:`PyMem_Free` 449 450 .. c:macro:: PYMEM_DOMAIN_OBJ 451 452 Functions: 453 454 * :c:func:`PyObject_Malloc` 455 * :c:func:`PyObject_Realloc` 456 * :c:func:`PyObject_Calloc` 457 * :c:func:`PyObject_Free` 458 459.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator) 460 461 Get the memory block allocator of the specified domain. 462 463 464.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator) 465 466 Set the memory block allocator of the specified domain. 467 468 The new allocator must return a distinct non-``NULL`` pointer when requesting 469 zero bytes. 470 471 For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be 472 thread-safe: the :term:`GIL <global interpreter lock>` is not held when the 473 allocator is called. 474 475 If the new allocator is not a hook (does not call the previous allocator), 476 the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the 477 debug hooks on top on the new allocator. 478 479 480.. c:function:: void PyMem_SetupDebugHooks(void) 481 482 Setup :ref:`debug hooks in the Python memory allocators <pymem-debug-hooks>` 483 to detect memory errors. 484 485 486.. _pymem-debug-hooks: 487 488Debug hooks on the Python memory allocators 489=========================================== 490 491When :ref:`Python is built in debug mode <debug-build>`, the 492:c:func:`PyMem_SetupDebugHooks` function is called at the :ref:`Python 493preinitialization <c-preinit>` to setup debug hooks on Python memory allocators 494to detect memory errors. 495 496The :envvar:`PYTHONMALLOC` environment variable can be used to install debug 497hooks on a Python compiled in release mode (ex: ``PYTHONMALLOC=debug``). 498 499The :c:func:`PyMem_SetupDebugHooks` function can be used to set debug hooks 500after calling :c:func:`PyMem_SetAllocator`. 501 502These debug hooks fill dynamically allocated memory blocks with special, 503recognizable bit patterns. Newly allocated memory is filled with the byte 504``0xCD`` (``PYMEM_CLEANBYTE``), freed memory is filled with the byte ``0xDD`` 505(``PYMEM_DEADBYTE``). Memory blocks are surrounded by "forbidden bytes" 506filled with the byte ``0xFD`` (``PYMEM_FORBIDDENBYTE``). Strings of these bytes 507are unlikely to be valid addresses, floats, or ASCII strings. 508 509Runtime checks: 510 511- Detect API violations. For example, detect if :c:func:`PyObject_Free` is 512 called on a memory block allocated by :c:func:`PyMem_Malloc`. 513- Detect write before the start of the buffer (buffer underflow). 514- Detect write after the end of the buffer (buffer overflow). 515- Check that the :term:`GIL <global interpreter lock>` is held when 516 allocator functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex: 517 :c:func:`PyObject_Malloc`) and :c:data:`PYMEM_DOMAIN_MEM` (ex: 518 :c:func:`PyMem_Malloc`) domains are called. 519 520On error, the debug hooks use the :mod:`tracemalloc` module to get the 521traceback where a memory block was allocated. The traceback is only displayed 522if :mod:`tracemalloc` is tracing Python memory allocations and the memory block 523was traced. 524 525Let *S* = ``sizeof(size_t)``. ``2*S`` bytes are added at each end of each block 526of *N* bytes requested. The memory layout is like so, where p represents the 527address returned by a malloc-like or realloc-like function (``p[i:j]`` means 528the slice of bytes from ``*(p+i)`` inclusive up to ``*(p+j)`` exclusive; note 529that the treatment of negative indices differs from a Python slice): 530 531``p[-2*S:-S]`` 532 Number of bytes originally asked for. This is a size_t, big-endian (easier 533 to read in a memory dump). 534``p[-S]`` 535 API identifier (ASCII character): 536 537 * ``'r'`` for :c:data:`PYMEM_DOMAIN_RAW`. 538 * ``'m'`` for :c:data:`PYMEM_DOMAIN_MEM`. 539 * ``'o'`` for :c:data:`PYMEM_DOMAIN_OBJ`. 540 541``p[-S+1:0]`` 542 Copies of PYMEM_FORBIDDENBYTE. Used to catch under- writes and reads. 543 544``p[0:N]`` 545 The requested memory, filled with copies of PYMEM_CLEANBYTE, used to catch 546 reference to uninitialized memory. When a realloc-like function is called 547 requesting a larger memory block, the new excess bytes are also filled with 548 PYMEM_CLEANBYTE. When a free-like function is called, these are 549 overwritten with PYMEM_DEADBYTE, to catch reference to freed memory. When 550 a realloc- like function is called requesting a smaller memory block, the 551 excess old bytes are also filled with PYMEM_DEADBYTE. 552 553``p[N:N+S]`` 554 Copies of PYMEM_FORBIDDENBYTE. Used to catch over- writes and reads. 555 556``p[N+S:N+2*S]`` 557 Only used if the ``PYMEM_DEBUG_SERIALNO`` macro is defined (not defined by 558 default). 559 560 A serial number, incremented by 1 on each call to a malloc-like or 561 realloc-like function. Big-endian ``size_t``. If "bad memory" is detected 562 later, the serial number gives an excellent way to set a breakpoint on the 563 next run, to capture the instant at which this block was passed out. The 564 static function bumpserialno() in obmalloc.c is the only place the serial 565 number is incremented, and exists so you can set such a breakpoint easily. 566 567A realloc-like or free-like function first checks that the PYMEM_FORBIDDENBYTE 568bytes at each end are intact. If they've been altered, diagnostic output is 569written to stderr, and the program is aborted via Py_FatalError(). The other 570main failure mode is provoking a memory error when a program reads up one of 571the special bit patterns and tries to use it as an address. If you get in a 572debugger then and look at the object, you're likely to see that it's entirely 573filled with PYMEM_DEADBYTE (meaning freed memory is getting used) or 574PYMEM_CLEANBYTE (meaning uninitialized memory is getting used). 575 576.. versionchanged:: 3.6 577 The :c:func:`PyMem_SetupDebugHooks` function now also works on Python 578 compiled in release mode. On error, the debug hooks now use 579 :mod:`tracemalloc` to get the traceback where a memory block was allocated. 580 The debug hooks now also check if the GIL is held when functions of 581 :c:data:`PYMEM_DOMAIN_OBJ` and :c:data:`PYMEM_DOMAIN_MEM` domains are 582 called. 583 584.. versionchanged:: 3.8 585 Byte patterns ``0xCB`` (``PYMEM_CLEANBYTE``), ``0xDB`` (``PYMEM_DEADBYTE``) 586 and ``0xFB`` (``PYMEM_FORBIDDENBYTE``) have been replaced with ``0xCD``, 587 ``0xDD`` and ``0xFD`` to use the same values than Windows CRT debug 588 ``malloc()`` and ``free()``. 589 590 591.. _pymalloc: 592 593The pymalloc allocator 594====================== 595 596Python has a *pymalloc* allocator optimized for small objects (smaller or equal 597to 512 bytes) with a short lifetime. It uses memory mappings called "arenas" 598with a fixed size of 256 KiB. It falls back to :c:func:`PyMem_RawMalloc` and 599:c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes. 600 601*pymalloc* is the :ref:`default allocator <default-memory-allocators>` of the 602:c:data:`PYMEM_DOMAIN_MEM` (ex: :c:func:`PyMem_Malloc`) and 603:c:data:`PYMEM_DOMAIN_OBJ` (ex: :c:func:`PyObject_Malloc`) domains. 604 605The arena allocator uses the following functions: 606 607* :c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows, 608* :c:func:`mmap` and :c:func:`munmap` if available, 609* :c:func:`malloc` and :c:func:`free` otherwise. 610 611This allocator is disabled if Python is configured with the 612:option:`--without-pymalloc` option. It can also be disabled at runtime using 613the :envvar:`PYTHONMALLOC` environment variable (ex: ``PYTHONMALLOC=malloc``). 614 615Customize pymalloc Arena Allocator 616---------------------------------- 617 618.. versionadded:: 3.4 619 620.. c:type:: PyObjectArenaAllocator 621 622 Structure used to describe an arena allocator. The structure has 623 three fields: 624 625 +--------------------------------------------------+---------------------------------------+ 626 | Field | Meaning | 627 +==================================================+=======================================+ 628 | ``void *ctx`` | user context passed as first argument | 629 +--------------------------------------------------+---------------------------------------+ 630 | ``void* alloc(void *ctx, size_t size)`` | allocate an arena of size bytes | 631 +--------------------------------------------------+---------------------------------------+ 632 | ``void free(void *ctx, void *ptr, size_t size)`` | free an arena | 633 +--------------------------------------------------+---------------------------------------+ 634 635.. c:function:: void PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator) 636 637 Get the arena allocator. 638 639.. c:function:: void PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator) 640 641 Set the arena allocator. 642 643 644tracemalloc C API 645================= 646 647.. versionadded:: 3.7 648 649.. c:function:: int PyTraceMalloc_Track(unsigned int domain, uintptr_t ptr, size_t size) 650 651 Track an allocated memory block in the :mod:`tracemalloc` module. 652 653 Return ``0`` on success, return ``-1`` on error (failed to allocate memory to 654 store the trace). Return ``-2`` if tracemalloc is disabled. 655 656 If memory block is already tracked, update the existing trace. 657 658.. c:function:: int PyTraceMalloc_Untrack(unsigned int domain, uintptr_t ptr) 659 660 Untrack an allocated memory block in the :mod:`tracemalloc` module. 661 Do nothing if the block was not tracked. 662 663 Return ``-2`` if tracemalloc is disabled, otherwise return ``0``. 664 665 666.. _memoryexamples: 667 668Examples 669======== 670 671Here is the example from section :ref:`memoryoverview`, rewritten so that the 672I/O buffer is allocated from the Python heap by using the first function set:: 673 674 PyObject *res; 675 char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */ 676 677 if (buf == NULL) 678 return PyErr_NoMemory(); 679 /* ...Do some I/O operation involving buf... */ 680 res = PyBytes_FromString(buf); 681 PyMem_Free(buf); /* allocated with PyMem_Malloc */ 682 return res; 683 684The same code using the type-oriented function set:: 685 686 PyObject *res; 687 char *buf = PyMem_New(char, BUFSIZ); /* for I/O */ 688 689 if (buf == NULL) 690 return PyErr_NoMemory(); 691 /* ...Do some I/O operation involving buf... */ 692 res = PyBytes_FromString(buf); 693 PyMem_Del(buf); /* allocated with PyMem_New */ 694 return res; 695 696Note that in the two examples above, the buffer is always manipulated via 697functions belonging to the same set. Indeed, it is required to use the same 698memory API family for a given memory block, so that the risk of mixing different 699allocators is reduced to a minimum. The following code sequence contains two 700errors, one of which is labeled as *fatal* because it mixes two different 701allocators operating on different heaps. :: 702 703 char *buf1 = PyMem_New(char, BUFSIZ); 704 char *buf2 = (char *) malloc(BUFSIZ); 705 char *buf3 = (char *) PyMem_Malloc(BUFSIZ); 706 ... 707 PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */ 708 free(buf2); /* Right -- allocated via malloc() */ 709 free(buf1); /* Fatal -- should be PyMem_Del() */ 710 711In addition to the functions aimed at handling raw memory blocks from the Python 712heap, objects in Python are allocated and released with :c:func:`PyObject_New`, 713:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`. 714 715These will be explained in the next chapter on defining and implementing new 716object types in C. 717