Green shading in the line number column means the source is part of the translation unit, red means it is conditionally excluded. Highlighted line numbers link to the translation unit page. Highlighted macros link to the macro page.
1: /* The PyMem_ family: low-level memory allocation interfaces. 2: See objimpl.h for the PyObject_ memory family. 3: */ 4: 5: #ifndef Py_PYMEM_H 6: #define Py_PYMEM_H 7: 8: #include "pyport.h" 9: 10: #ifdef __cplusplus 11: extern "C" { 12: #endif 13: 14: #ifndef Py_LIMITED_API 15: PyAPI_FUNC(void *) PyMem_RawMalloc(size_t size); 16: PyAPI_FUNC(void *) PyMem_RawCalloc(size_t nelem, size_t elsize); 17: PyAPI_FUNC(void *) PyMem_RawRealloc(void *ptr, size_t new_size); 18: PyAPI_FUNC(void) PyMem_RawFree(void *ptr); 19: 20: /* Configure the Python memory allocators. Pass NULL to use default 21: allocators. */ 22: PyAPI_FUNC(int) _PyMem_SetupAllocators(const char *opt); 23: 24: #ifdef WITH_PYMALLOC 25: PyAPI_FUNC(int) _PyMem_PymallocEnabled(void); 26: #endif 27: 28: /* Identifier of an address space (domain) in tracemalloc */ 29: typedef unsigned int _PyTraceMalloc_domain_t; 30: 31: /* Track an allocated memory block in the tracemalloc module. 32: Return 0 on success, return -1 on error (failed to allocate memory to store 33: the trace). 34: 35: Return -2 if tracemalloc is disabled. 36: 37: If memory block is already tracked, update the existing trace. */ 38: PyAPI_FUNC(int) _PyTraceMalloc_Track( 39: _PyTraceMalloc_domain_t domain, 40: uintptr_t ptr, 41: size_t size); 42: 43: /* Untrack an allocated memory block in the tracemalloc module. 44: Do nothing if the block was not tracked. 45: 46: Return -2 if tracemalloc is disabled, otherwise return 0. */ 47: PyAPI_FUNC(int) _PyTraceMalloc_Untrack( 48: _PyTraceMalloc_domain_t domain, 49: uintptr_t ptr); 50: 51: /* Get the traceback where a memory block was allocated. 52: 53: Return a tuple of (filename: str, lineno: int) tuples. 54: 55: Return None if the tracemalloc module is disabled or if the memory block 56: is not tracked by tracemalloc. 57: 58: Raise an exception and return NULL on error. */ 59: PyAPI_FUNC(PyObject*) _PyTraceMalloc_GetTraceback( 60: _PyTraceMalloc_domain_t domain, 61: uintptr_t ptr); 62: #endif /* !Py_LIMITED_API */ 63: 64: 65: /* BEWARE: 66: 67: Each interface exports both functions and macros. Extension modules should 68: use the functions, to ensure binary compatibility across Python versions. 69: Because the Python implementation is free to change internal details, and 70: the macros may (or may not) expose details for speed, if you do use the 71: macros you must recompile your extensions with each Python release. 72: 73: Never mix calls to PyMem_ with calls to the platform malloc/realloc/ 74: calloc/free. For example, on Windows different DLLs may end up using 75: different heaps, and if you use PyMem_Malloc you'll get the memory from the 76: heap used by the Python DLL; it could be a disaster if you free()'ed that 77: directly in your own extension. Using PyMem_Free instead ensures Python 78: can return the memory to the proper heap. As another example, in 79: PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_ 80: memory functions in special debugging wrappers that add additional 81: debugging info to dynamic memory blocks. The system routines have no idea 82: what to do with that stuff, and the Python wrappers have no idea what to do 83: with raw blocks obtained directly by the system routines then. 84: 85: The GIL must be held when using these APIs. 86: */ 87: 88: /* 89: * Raw memory interface 90: * ==================== 91: */ 92: 93: /* Functions 94: 95: Functions supplying platform-independent semantics for malloc/realloc/ 96: free. These functions make sure that allocating 0 bytes returns a distinct 97: non-NULL pointer (whenever possible -- if we're flat out of memory, NULL 98: may be returned), even if the platform malloc and realloc don't. 99: Returned pointers must be checked for NULL explicitly. No action is 100: performed on failure (no exception is set, no warning is printed, etc). 101: */ 102: 103: PyAPI_FUNC(void *) PyMem_Malloc(size_t size); 104: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000 105: PyAPI_FUNC(void *) PyMem_Calloc(size_t nelem, size_t elsize); 106: #endif 107: PyAPI_FUNC(void *) PyMem_Realloc(void *ptr, size_t new_size); 108: PyAPI_FUNC(void) PyMem_Free(void *ptr); 109: 110: #ifndef Py_LIMITED_API 111: PyAPI_FUNC(char *) _PyMem_RawStrdup(const char *str); 112: PyAPI_FUNC(char *) _PyMem_Strdup(const char *str); 113: #endif 114: 115: /* Macros. */ 116: 117: /* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL 118: for malloc(0), which would be treated as an error. Some platforms 119: would return a pointer with no memory behind it, which would break 120: pymalloc. To solve these problems, allocate an extra byte. */ 121: /* Returns NULL to indicate error if a negative size or size larger than 122: Py_ssize_t can represent is supplied. Helps prevents security holes. */ 123: #define PyMem_MALLOC(n) PyMem_Malloc(n) 124: #define PyMem_REALLOC(p, n) PyMem_Realloc(p, n) 125: #define PyMem_FREE(p) PyMem_Free(p) 126: 127: /* 128: * Type-oriented memory interface 129: * ============================== 130: * 131: * Allocate memory for n objects of the given type. Returns a new pointer 132: * or NULL if the request was too large or memory allocation failed. Use 133: * these macros rather than doing the multiplication yourself so that proper 134: * overflow checking is always done. 135: */ 136: 137: #define PyMem_New(type, n) \ 138: ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ 139: ( (type *) PyMem_Malloc((n) * sizeof(type)) ) ) 140: #define PyMem_NEW(type, n) \ 141: ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ 142: ( (type *) PyMem_MALLOC((n) * sizeof(type)) ) ) 143: 144: /* 145: * The value of (p) is always clobbered by this macro regardless of success. 146: * The caller MUST check if (p) is NULL afterwards and deal with the memory 147: * error if so. This means the original value of (p) MUST be saved for the 148: * caller's memory error handler to not lose track of it. 149: */ 150: #define PyMem_Resize(p, type, n) \ 151: ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ 152: (type *) PyMem_Realloc((p), (n) * sizeof(type)) ) 153: #define PyMem_RESIZE(p, type, n) \ 154: ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ 155: (type *) PyMem_REALLOC((p), (n) * sizeof(type)) ) 156: 157: /* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used 158: * anymore. They're just confusing aliases for PyMem_{Free,FREE} now. 159: */ 160: #define PyMem_Del PyMem_Free 161: #define PyMem_DEL PyMem_FREE 162: 163: #ifndef Py_LIMITED_API 164: typedef enum { 165: /* PyMem_RawMalloc(), PyMem_RawRealloc() and PyMem_RawFree() */ 166: PYMEM_DOMAIN_RAW, 167: 168: /* PyMem_Malloc(), PyMem_Realloc() and PyMem_Free() */ 169: PYMEM_DOMAIN_MEM, 170: 171: /* PyObject_Malloc(), PyObject_Realloc() and PyObject_Free() */ 172: PYMEM_DOMAIN_OBJ 173: } PyMemAllocatorDomain; 174: 175: typedef struct { 176: /* user context passed as the first argument to the 4 functions */ 177: void *ctx; 178: 179: /* allocate a memory block */ 180: void* (*malloc) (void *ctx, size_t size); 181: 182: /* allocate a memory block initialized by zeros */ 183: void* (*calloc) (void *ctx, size_t nelem, size_t elsize); 184: 185: /* allocate or resize a memory block */ 186: void* (*realloc) (void *ctx, void *ptr, size_t new_size); 187: 188: /* release a memory block */ 189: void (*free) (void *ctx, void *ptr); 190: } PyMemAllocatorEx; 191: 192: /* Get the memory block allocator of the specified domain. */ 193: PyAPI_FUNC(void) PyMem_GetAllocator(PyMemAllocatorDomain domain, 194: PyMemAllocatorEx *allocator); 195: 196: /* Set the memory block allocator of the specified domain. 197: 198: The new allocator must return a distinct non-NULL pointer when requesting 199: zero bytes. 200: 201: For the PYMEM_DOMAIN_RAW domain, the allocator must be thread-safe: the GIL 202: is not held when the allocator is called. 203: 204: If the new allocator is not a hook (don't call the previous allocator), the 205: PyMem_SetupDebugHooks() function must be called to reinstall the debug hooks 206: on top on the new allocator. */ 207: PyAPI_FUNC(void) PyMem_SetAllocator(PyMemAllocatorDomain domain, 208: PyMemAllocatorEx *allocator); 209: 210: /* Setup hooks to detect bugs in the following Python memory allocator 211: functions: 212: 213: - PyMem_RawMalloc(), PyMem_RawRealloc(), PyMem_RawFree() 214: - PyMem_Malloc(), PyMem_Realloc(), PyMem_Free() 215: - PyObject_Malloc(), PyObject_Realloc() and PyObject_Free() 216: 217: Newly allocated memory is filled with the byte 0xCB, freed memory is filled 218: with the byte 0xDB. Additionnal checks: 219: 220: - detect API violations, ex: PyObject_Free() called on a buffer allocated 221: by PyMem_Malloc() 222: - detect write before the start of the buffer (buffer underflow) 223: - detect write after the end of the buffer (buffer overflow) 224: 225: The function does nothing if Python is not compiled is debug mode. */ 226: PyAPI_FUNC(void) PyMem_SetupDebugHooks(void); 227: #endif 228: 229: #ifdef __cplusplus 230: } 231: #endif 232: 233: #endif /* !Py_PYMEM_H */ 234: