Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 1 | /* The PyMem_ family: low-level memory allocation interfaces. |
| 2 | See objimpl.h for the PyObject_ memory family. |
| 3 | */ |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 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 | |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 14 | /* BEWARE: |
| 15 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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. |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 21 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 360e4b8 | 2007-05-14 22:51:27 +0000 | [diff] [blame] | 33 | |
| 34 | The GIL must be held when using these APIs. |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 35 | */ |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 36 | |
| 37 | /* |
| 38 | * Raw memory interface |
| 39 | * ==================== |
| 40 | */ |
| 41 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 42 | /* Functions |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 43 | |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 44 | Functions supplying platform-independent semantics for malloc/realloc/ |
| 45 | free. These functions make sure that allocating 0 bytes returns a distinct |
Tim Peters | af3e8de | 2002-04-12 07:22:56 +0000 | [diff] [blame] | 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 |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 49 | performed on failure (no exception is set, no warning is printed, etc). |
| 50 | */ |
Tim Peters | af3e8de | 2002-04-12 07:22:56 +0000 | [diff] [blame] | 51 | |
Victor Stinner | 0507bf5 | 2013-07-07 02:05:46 +0200 | [diff] [blame] | 52 | PyAPI_FUNC(void *) PyMem_Malloc(size_t size); |
| 53 | PyAPI_FUNC(void *) PyMem_Realloc(void *ptr, size_t new_size); |
| 54 | PyAPI_FUNC(void) PyMem_Free(void *ptr); |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 55 | |
Tim Peters | af3e8de | 2002-04-12 07:22:56 +0000 | [diff] [blame] | 56 | /* Macros. */ |
Tim Peters | 51e7f5c | 2002-04-22 02:33:27 +0000 | [diff] [blame] | 57 | |
Martin v. Löwis | 39f59b0 | 2002-11-23 09:13:40 +0000 | [diff] [blame] | 58 | /* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL |
| 59 | for malloc(0), which would be treated as an error. Some platforms |
| 60 | would return a pointer with no memory behind it, which would break |
| 61 | pymalloc. To solve these problems, allocate an extra byte. */ |
Georg Brandl | d492ad8 | 2008-07-23 16:13:07 +0000 | [diff] [blame] | 62 | /* Returns NULL to indicate error if a negative size or size larger than |
| 63 | Py_ssize_t can represent is supplied. Helps prevents security holes. */ |
Victor Stinner | 0507bf5 | 2013-07-07 02:05:46 +0200 | [diff] [blame] | 64 | #define PyMem_MALLOC(n) PyMem_Malloc(n) |
| 65 | #define PyMem_REALLOC(p, n) PyMem_Realloc(p, n) |
| 66 | #define PyMem_FREE(p) PyMem_Free(p) |
Tim Peters | af3e8de | 2002-04-12 07:22:56 +0000 | [diff] [blame] | 67 | |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 68 | /* |
| 69 | * Type-oriented memory interface |
| 70 | * ============================== |
Tim Peters | af3e8de | 2002-04-12 07:22:56 +0000 | [diff] [blame] | 71 | * |
Georg Brandl | d492ad8 | 2008-07-23 16:13:07 +0000 | [diff] [blame] | 72 | * Allocate memory for n objects of the given type. Returns a new pointer |
| 73 | * or NULL if the request was too large or memory allocation failed. Use |
| 74 | * these macros rather than doing the multiplication yourself so that proper |
| 75 | * overflow checking is always done. |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 76 | */ |
| 77 | |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 78 | #define PyMem_New(type, n) \ |
luzpaz | a5293b4 | 2017-11-05 07:37:50 -0600 | [diff] [blame] | 79 | ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ |
| 80 | ( (type *) PyMem_Malloc((n) * sizeof(type)) ) ) |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 81 | #define PyMem_NEW(type, n) \ |
luzpaz | a5293b4 | 2017-11-05 07:37:50 -0600 | [diff] [blame] | 82 | ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ |
| 83 | ( (type *) PyMem_MALLOC((n) * sizeof(type)) ) ) |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 84 | |
Georg Brandl | d492ad8 | 2008-07-23 16:13:07 +0000 | [diff] [blame] | 85 | /* |
| 86 | * The value of (p) is always clobbered by this macro regardless of success. |
| 87 | * The caller MUST check if (p) is NULL afterwards and deal with the memory |
| 88 | * error if so. This means the original value of (p) MUST be saved for the |
| 89 | * caller's memory error handler to not lose track of it. |
| 90 | */ |
Tim Peters | 8b078f9 | 2002-04-28 04:11:46 +0000 | [diff] [blame] | 91 | #define PyMem_Resize(p, type, n) \ |
luzpaz | a5293b4 | 2017-11-05 07:37:50 -0600 | [diff] [blame] | 92 | ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ |
| 93 | (type *) PyMem_Realloc((p), (n) * sizeof(type)) ) |
Tim Peters | af3e8de | 2002-04-12 07:22:56 +0000 | [diff] [blame] | 94 | #define PyMem_RESIZE(p, type, n) \ |
luzpaz | a5293b4 | 2017-11-05 07:37:50 -0600 | [diff] [blame] | 95 | ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ |
| 96 | (type *) PyMem_REALLOC((p), (n) * sizeof(type)) ) |
Tim Peters | a5d78cc | 2002-03-02 08:43:19 +0000 | [diff] [blame] | 97 | |
Thomas Wouters | 49fd7fa | 2006-04-21 10:40:58 +0000 | [diff] [blame] | 98 | /* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used |
| 99 | * anymore. They're just confusing aliases for PyMem_{Free,FREE} now. |
| 100 | */ |
luzpaz | a5293b4 | 2017-11-05 07:37:50 -0600 | [diff] [blame] | 101 | #define PyMem_Del PyMem_Free |
| 102 | #define PyMem_DEL PyMem_FREE |
Tim Peters | ddea208 | 2002-03-23 10:03:50 +0000 | [diff] [blame] | 103 | |
Victor Stinner | 9e00e80 | 2018-10-25 13:31:16 +0200 | [diff] [blame] | 104 | /* bpo-35053: expose _Py_tracemalloc_config for performance: |
| 105 | _Py_NewReference() needs an efficient check to test if tracemalloc is |
Victor Stinner | 6279c1c | 2018-10-25 15:54:13 +0200 | [diff] [blame] | 106 | tracing. |
| 107 | |
| 108 | It has to be defined in pymem.h, before object.h is included. */ |
Victor Stinner | 9e00e80 | 2018-10-25 13:31:16 +0200 | [diff] [blame] | 109 | struct _PyTraceMalloc_Config { |
| 110 | /* Module initialized? |
| 111 | Variable protected by the GIL */ |
| 112 | enum { |
| 113 | TRACEMALLOC_NOT_INITIALIZED, |
| 114 | TRACEMALLOC_INITIALIZED, |
| 115 | TRACEMALLOC_FINALIZED |
| 116 | } initialized; |
| 117 | |
| 118 | /* Is tracemalloc tracing memory allocations? |
| 119 | Variable protected by the GIL */ |
| 120 | int tracing; |
| 121 | |
| 122 | /* limit of the number of frames in a traceback, 1 by default. |
| 123 | Variable protected by the GIL. */ |
| 124 | int max_nframe; |
| 125 | |
| 126 | /* use domain in trace key? |
| 127 | Variable protected by the GIL. */ |
| 128 | int use_domain; |
| 129 | }; |
| 130 | |
| 131 | PyAPI_DATA(struct _PyTraceMalloc_Config) _Py_tracemalloc_config; |
| 132 | |
| 133 | #define _PyTraceMalloc_Config_INIT \ |
| 134 | {.initialized = TRACEMALLOC_NOT_INITIALIZED, \ |
| 135 | .tracing = 0, \ |
| 136 | .max_nframe = 1, \ |
| 137 | .use_domain = 0} |
| 138 | |
Victor Stinner | 9820c07 | 2019-04-15 17:00:19 +0200 | [diff] [blame] | 139 | |
| 140 | #ifndef Py_LIMITED_API |
| 141 | # define Py_CPYTHON_PYMEM_H |
| 142 | # include "cpython/pymem.h" |
| 143 | # undef Py_CPYTHON_PYMEM_H |
| 144 | #endif |
| 145 | |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 146 | #ifdef __cplusplus |
| 147 | } |
| 148 | #endif |
| 149 | |
Peter Schneider-Kamp | 25f6894 | 2000-07-31 22:19:30 +0000 | [diff] [blame] | 150 | #endif /* !Py_PYMEM_H */ |