pymem.h revision 9c74b14fe9b6dddc9d41dd37f431f174350004d4
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 11extern "C" { 12#endif 13 14/* BEWARE: 15 16 Each interface exports both functions and macros. Extension modules should 17 use the functions, to ensure binary compatibility across Python versions. 18 Because the Python implementation is free to change internal details, and 19 the macros may (or may not) expose details for speed, if you do use the 20 macros you must recompile your extensions with each Python release. 21 22 Never mix calls to PyMem_ with calls to the platform malloc/realloc/ 23 calloc/free. For example, on Windows different DLLs may end up using 24 different heaps, and if you use PyMem_Malloc you'll get the memory from the 25 heap used by the Python DLL; it could be a disaster if you free()'ed that 26 directly in your own extension. Using PyMem_Free instead ensures Python 27 can return the memory to the proper heap. As another example, in 28 PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_ 29 memory functions in special debugging wrappers that add additional 30 debugging info to dynamic memory blocks. The system routines have no idea 31 what to do with that stuff, and the Python wrappers have no idea what to do 32 with raw blocks obtained directly by the system routines then. 33 34 The GIL must be held when using these APIs. 35*/ 36 37/* 38 * Raw memory interface 39 * ==================== 40 */ 41 42/* Functions 43 44 Functions supplying platform-independent semantics for malloc/realloc/ 45 free. These functions make sure that allocating 0 bytes returns a distinct 46 non-NULL pointer (whenever possible -- if we're flat out of memory, NULL 47 may be returned), even if the platform malloc and realloc don't. 48 Returned pointers must be checked for NULL explicitly. No action is 49 performed on failure (no exception is set, no warning is printed, etc). 50*/ 51 52PyAPI_FUNC(void *) PyMem_Malloc(size_t); 53PyAPI_FUNC(void *) PyMem_Realloc(void *, size_t); 54PyAPI_FUNC(void) PyMem_Free(void *); 55 56/* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are 57 no longer supported. They used to call PyErr_NoMemory() on failure. */ 58 59/* Macros. */ 60#ifdef PYMALLOC_DEBUG 61/* Redirect all memory operations to Python's debugging allocator. */ 62#define PyMem_MALLOC PyObject_MALLOC 63#define PyMem_REALLOC PyObject_REALLOC 64#define PyMem_FREE PyObject_FREE 65 66#else /* ! PYMALLOC_DEBUG */ 67 68/* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL 69 for malloc(0), which would be treated as an error. Some platforms 70 would return a pointer with no memory behind it, which would break 71 pymalloc. To solve these problems, allocate an extra byte. */ 72#define PyMem_MALLOC(n) malloc((n) ? (n) : 1) 73#define PyMem_REALLOC(p, n) realloc((p), (n) ? (n) : 1) 74#define PyMem_FREE free 75 76#endif /* PYMALLOC_DEBUG */ 77 78/* 79 * Type-oriented memory interface 80 * ============================== 81 * 82 * These are carried along for historical reasons. There's rarely a good 83 * reason to use them anymore (you can just as easily do the multiply and 84 * cast yourself). 85 */ 86 87#define PyMem_New(type, n) \ 88 ( assert((n) <= PY_SIZE_MAX / sizeof(type)) , \ 89 ( (type *) PyMem_Malloc((n) * sizeof(type)) ) ) 90#define PyMem_NEW(type, n) \ 91 ( assert((n) <= PY_SIZE_MAX / sizeof(type)) , \ 92 ( (type *) PyMem_MALLOC((n) * sizeof(type)) ) ) 93 94#define PyMem_Resize(p, type, n) \ 95 ( assert((n) <= PY_SIZE_MAX / sizeof(type)) , \ 96 ( (p) = (type *) PyMem_Realloc((p), (n) * sizeof(type)) ) ) 97#define PyMem_RESIZE(p, type, n) \ 98 ( assert((n) <= PY_SIZE_MAX / sizeof(type)) , \ 99 ( (p) = (type *) PyMem_REALLOC((p), (n) * sizeof(type)) ) ) 100 101/* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used 102 * anymore. They're just confusing aliases for PyMem_{Free,FREE} now. 103 */ 104#define PyMem_Del PyMem_Free 105#define PyMem_DEL PyMem_FREE 106 107#ifdef __cplusplus 108} 109#endif 110 111#endif /* !Py_PYMEM_H */ 112