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