python3.12/cpython/pymem.h

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