| 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 | /* 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 |
|
|---|
| 35 | /*
|
|---|
| 36 | * Raw memory interface
|
|---|
| 37 | * ====================
|
|---|
| 38 | */
|
|---|
| 39 |
|
|---|
| 40 | /* Functions
|
|---|
| 41 |
|
|---|
| 42 | Functions supplying platform-independent semantics for malloc/realloc/
|
|---|
| 43 | free. These functions make sure that allocating 0 bytes returns a distinct
|
|---|
| 44 | non-NULL pointer (whenever possible -- if we're flat out of memory, NULL
|
|---|
| 45 | may be returned), even if the platform malloc and realloc don't.
|
|---|
| 46 | Returned pointers must be checked for NULL explicitly. No action is
|
|---|
| 47 | performed on failure (no exception is set, no warning is printed, etc).
|
|---|
| 48 | */
|
|---|
| 49 |
|
|---|
| 50 | PyAPI_FUNC(void *) PyMem_Malloc(size_t);
|
|---|
| 51 | PyAPI_FUNC(void *) PyMem_Realloc(void *, size_t);
|
|---|
| 52 | PyAPI_FUNC(void) PyMem_Free(void *);
|
|---|
| 53 |
|
|---|
| 54 | /* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are
|
|---|
| 55 | no longer supported. They used to call PyErr_NoMemory() on failure. */
|
|---|
| 56 |
|
|---|
| 57 | /* Macros. */
|
|---|
| 58 | #ifdef PYMALLOC_DEBUG
|
|---|
| 59 | /* Redirect all memory operations to Python's debugging allocator. */
|
|---|
| 60 | #define PyMem_MALLOC PyObject_MALLOC
|
|---|
| 61 | #define PyMem_REALLOC PyObject_REALLOC
|
|---|
| 62 | #define PyMem_FREE PyObject_FREE
|
|---|
| 63 |
|
|---|
| 64 | #else /* ! PYMALLOC_DEBUG */
|
|---|
| 65 |
|
|---|
| 66 | /* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL
|
|---|
| 67 | for malloc(0), which would be treated as an error. Some platforms
|
|---|
| 68 | would return a pointer with no memory behind it, which would break
|
|---|
| 69 | pymalloc. To solve these problems, allocate an extra byte. */
|
|---|
| 70 | #define PyMem_MALLOC(n) malloc((n) ? (n) : 1)
|
|---|
| 71 | #define PyMem_REALLOC(p, n) realloc((p), (n) ? (n) : 1)
|
|---|
| 72 | #define PyMem_FREE free
|
|---|
| 73 |
|
|---|
| 74 | #endif /* PYMALLOC_DEBUG */
|
|---|
| 75 |
|
|---|
| 76 | /*
|
|---|
| 77 | * Type-oriented memory interface
|
|---|
| 78 | * ==============================
|
|---|
| 79 | *
|
|---|
| 80 | * These are carried along for historical reasons. There's rarely a good
|
|---|
| 81 | * reason to use them anymore (you can just as easily do the multiply and
|
|---|
| 82 | * cast yourself).
|
|---|
| 83 | */
|
|---|
| 84 |
|
|---|
| 85 | #define PyMem_New(type, n) \
|
|---|
| 86 | ( (type *) PyMem_Malloc((n) * sizeof(type)) )
|
|---|
| 87 | #define PyMem_NEW(type, n) \
|
|---|
| 88 | ( (type *) PyMem_MALLOC((n) * sizeof(type)) )
|
|---|
| 89 |
|
|---|
| 90 | #define PyMem_Resize(p, type, n) \
|
|---|
| 91 | ( (p) = (type *) PyMem_Realloc((p), (n) * sizeof(type)) )
|
|---|
| 92 | #define PyMem_RESIZE(p, type, n) \
|
|---|
| 93 | ( (p) = (type *) PyMem_REALLOC((p), (n) * sizeof(type)) )
|
|---|
| 94 |
|
|---|
| 95 | /* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used
|
|---|
| 96 | * anymore. They're just confusing aliases for PyMem_{Free,FREE} now.
|
|---|
| 97 | */
|
|---|
| 98 | #define PyMem_Del PyMem_Free
|
|---|
| 99 | #define PyMem_DEL PyMem_FREE
|
|---|
| 100 |
|
|---|
| 101 | #ifdef __cplusplus
|
|---|
| 102 | }
|
|---|
| 103 | #endif
|
|---|
| 104 |
|
|---|
| 105 | #endif /* !Py_PYMEM_H */
|
|---|
