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