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#ifndef Py_LIMITED_API
15PyAPI_FUNC(void *) PyMem_RawMalloc(size_t size);
16PyAPI_FUNC(void *) PyMem_RawCalloc(size_t nelem, size_t elsize);
17PyAPI_FUNC(void *) PyMem_RawRealloc(void *ptr, size_t new_size);
18PyAPI_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
60PyAPI_FUNC(void *) PyMem_Malloc(size_t size);
61PyAPI_FUNC(void *) PyMem_Calloc(size_t nelem, size_t elsize);
62PyAPI_FUNC(void *) PyMem_Realloc(void *ptr, size_t new_size);
63PyAPI_FUNC(void) PyMem_Free(void *ptr);
64
65#ifndef Py_LIMITED_API
66PyAPI_FUNC(char *) _PyMem_RawStrdup(const char *str);
67PyAPI_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
119typedef 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
130typedef 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. */
148PyAPI_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. */
162PyAPI_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. */
181PyAPI_FUNC(void) PyMem_SetupDebugHooks(void);
182#endif
183
184#ifdef __cplusplus
185}
186#endif
187
188#endif /* !Py_PYMEM_H */
189