1 // The PyMem_ family: low-level memory allocation interfaces. 2 // See objimpl.h for the PyObject_ memory family. 3 4 #ifndef Py_PYMEM_H 5 #define Py_PYMEM_H 6 #ifdef __cplusplus 7 extern "C" { 8 #endif 9 10 /* BEWARE: 11 12 Each interface exports both functions and macros. Extension modules should 13 use the functions, to ensure binary compatibility across Python versions. 14 Because the Python implementation is free to change internal details, and 15 the macros may (or may not) expose details for speed, if you do use the 16 macros you must recompile your extensions with each Python release. 17 18 Never mix calls to PyMem_ with calls to the platform malloc/realloc/ 19 calloc/free. For example, on Windows different DLLs may end up using 20 different heaps, and if you use PyMem_Malloc you'll get the memory from the 21 heap used by the Python DLL; it could be a disaster if you free()'ed that 22 directly in your own extension. Using PyMem_Free instead ensures Python 23 can return the memory to the proper heap. As another example, in 24 a debug build (Py_DEBUG macro), Python wraps all calls to all PyMem_ and 25 PyObject_ memory functions in special debugging wrappers that add additional 26 debugging info to dynamic memory blocks. The system routines have no idea 27 what to do with that stuff, and the Python wrappers have no idea what to do 28 with raw blocks obtained directly by the system routines then. 29 30 The GIL must be held when using these APIs. 31 */ 32 33 /* 34 * Raw memory interface 35 * ==================== 36 */ 37 38 /* Functions 39 40 Functions supplying platform-independent semantics for malloc/realloc/ 41 free. These functions make sure that allocating 0 bytes returns a distinct 42 non-NULL pointer (whenever possible -- if we're flat out of memory, NULL 43 may be returned), even if the platform malloc and realloc don't. 44 Returned pointers must be checked for NULL explicitly. No action is 45 performed on failure (no exception is set, no warning is printed, etc). 46 */ 47 48 PyAPI_FUNC(void *) PyMem_Malloc(size_t size); 49 PyAPI_FUNC(void *) PyMem_Calloc(size_t nelem, size_t elsize); 50 PyAPI_FUNC(void *) PyMem_Realloc(void *ptr, size_t new_size); 51 PyAPI_FUNC(void) PyMem_Free(void *ptr); 52 53 /* 54 * Type-oriented memory interface 55 * ============================== 56 * 57 * Allocate memory for n objects of the given type. Returns a new pointer 58 * or NULL if the request was too large or memory allocation failed. Use 59 * these macros rather than doing the multiplication yourself so that proper 60 * overflow checking is always done. 61 */ 62 63 #define PyMem_New(type, n) \ 64 ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ 65 ( (type *) PyMem_Malloc((n) * sizeof(type)) ) ) 66 67 /* 68 * The value of (p) is always clobbered by this macro regardless of success. 69 * The caller MUST check if (p) is NULL afterwards and deal with the memory 70 * error if so. This means the original value of (p) MUST be saved for the 71 * caller's memory error handler to not lose track of it. 72 */ 73 #define PyMem_Resize(p, type, n) \ 74 ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ 75 (type *) PyMem_Realloc((p), (n) * sizeof(type)) ) 76 77 78 // Deprecated aliases only kept for backward compatibility. 79 // PyMem_Del and PyMem_DEL are defined with no parameter to be able to use 80 // them as function pointers (ex: dealloc = PyMem_Del). 81 #define PyMem_MALLOC(n) PyMem_Malloc((n)) 82 #define PyMem_NEW(type, n) PyMem_New(type, (n)) 83 #define PyMem_REALLOC(p, n) PyMem_Realloc((p), (n)) 84 #define PyMem_RESIZE(p, type, n) PyMem_Resize((p), type, (n)) 85 #define PyMem_FREE(p) PyMem_Free((p)) 86 #define PyMem_Del(p) PyMem_Free((p)) 87 #define PyMem_DEL(p) PyMem_Free((p)) 88 89 90 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000 91 // Memory allocator which doesn't require the GIL to be held. 92 // Usually, it's just a thin wrapper to functions of the standard C library: 93 // malloc(), calloc(), realloc() and free(). The difference is that 94 // tracemalloc can track these memory allocations. 95 PyAPI_FUNC(void *) PyMem_RawMalloc(size_t size); 96 PyAPI_FUNC(void *) PyMem_RawCalloc(size_t nelem, size_t elsize); 97 PyAPI_FUNC(void *) PyMem_RawRealloc(void *ptr, size_t new_size); 98 PyAPI_FUNC(void) PyMem_RawFree(void *ptr); 99 #endif 100 101 #ifndef Py_LIMITED_API 102 # define Py_CPYTHON_PYMEM_H 103 # include "cpython/pymem.h" 104 # undef Py_CPYTHON_PYMEM_H 105 #endif 106 107 #ifdef __cplusplus 108 } 109 #endif 110 #endif // !Py_PYMEM_H 111