python3.13/cpython/pymem.h

0001 #ifndef Py_CPYTHON_PYMEM_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005 typedef enum {
0006     /* PyMem_RawMalloc(), PyMem_RawRealloc() and PyMem_RawFree() */
0007     PYMEM_DOMAIN_RAW,
0008
0009     /* PyMem_Malloc(), PyMem_Realloc() and PyMem_Free() */
0010     PYMEM_DOMAIN_MEM,
0011
0012     /* PyObject_Malloc(), PyObject_Realloc() and PyObject_Free() */
0013     PYMEM_DOMAIN_OBJ
0014 } PyMemAllocatorDomain;
0015
0016 typedef enum {
0017     PYMEM_ALLOCATOR_NOT_SET = 0,
0018     PYMEM_ALLOCATOR_DEFAULT = 1,
0019     PYMEM_ALLOCATOR_DEBUG = 2,
0020     PYMEM_ALLOCATOR_MALLOC = 3,
0021     PYMEM_ALLOCATOR_MALLOC_DEBUG = 4,
0022 #ifdef WITH_PYMALLOC
0023     PYMEM_ALLOCATOR_PYMALLOC = 5,
0024     PYMEM_ALLOCATOR_PYMALLOC_DEBUG = 6,
0025 #endif
0026 #ifdef WITH_MIMALLOC
0027     PYMEM_ALLOCATOR_MIMALLOC = 7,
0028     PYMEM_ALLOCATOR_MIMALLOC_DEBUG = 8,
0029 #endif
0030 } PyMemAllocatorName;
0031
0032
0033 typedef struct {
0034     /* user context passed as the first argument to the 4 functions */
0035     void *ctx;
0036
0037     /* allocate a memory block */
0038     void* (*malloc) (void *ctx, size_t size);
0039
0040     /* allocate a memory block initialized by zeros */
0041     void* (*calloc) (void *ctx, size_t nelem, size_t elsize);
0042
0043     /* allocate or resize a memory block */
0044     void* (*realloc) (void *ctx, void *ptr, size_t new_size);
0045
0046     /* release a memory block */
0047     void (*free) (void *ctx, void *ptr);
0048 } PyMemAllocatorEx;
0049
0050 /* Get the memory block allocator of the specified domain. */
0051 PyAPI_FUNC(void) PyMem_GetAllocator(PyMemAllocatorDomain domain,
0052                                     PyMemAllocatorEx *allocator);
0053
0054 /* Set the memory block allocator of the specified domain.
0055
0056    The new allocator must return a distinct non-NULL pointer when requesting
0057    zero bytes.
0058
0059    For the PYMEM_DOMAIN_RAW domain, the allocator must be thread-safe: the GIL
0060    is not held when the allocator is called.
0061
0062    If the new allocator is not a hook (don't call the previous allocator), the
0063    PyMem_SetupDebugHooks() function must be called to reinstall the debug hooks
0064    on top on the new allocator. */
0065 PyAPI_FUNC(void) PyMem_SetAllocator(PyMemAllocatorDomain domain,
0066                                     PyMemAllocatorEx *allocator);
0067
0068 /* Setup hooks to detect bugs in the following Python memory allocator
0069    functions:
0070
0071    - PyMem_RawMalloc(), PyMem_RawRealloc(), PyMem_RawFree()
0072    - PyMem_Malloc(), PyMem_Realloc(), PyMem_Free()
0073    - PyObject_Malloc(), PyObject_Realloc() and PyObject_Free()
0074
0075    Newly allocated memory is filled with the byte 0xCB, freed memory is filled
0076    with the byte 0xDB. Additional checks:
0077
0078    - detect API violations, ex: PyObject_Free() called on a buffer allocated
0079      by PyMem_Malloc()
0080    - detect write before the start of the buffer (buffer underflow)
0081    - detect write after the end of the buffer (buffer overflow)
0082
0083    The function does nothing if Python is not compiled is debug mode. */
0084 PyAPI_FUNC(void) PyMem_SetupDebugHooks(void);