|
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 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 |
|
52 PyAPI_FUNC(void *) PyMem_Malloc(size_t); |
|
53 PyAPI_FUNC(void *) PyMem_Realloc(void *, size_t); |
|
54 PyAPI_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 /* Returns NULL to indicate error if a negative size or size larger than |
|
73 Py_ssize_t can represent is supplied. Helps prevents security holes. */ |
|
74 #define PyMem_MALLOC(n) (((n) < 0 || (n) > PY_SSIZE_T_MAX) ? NULL \ |
|
75 : malloc((n) ? (n) : 1)) |
|
76 #define PyMem_REALLOC(p, n) (((n) < 0 || (n) > PY_SSIZE_T_MAX) ? NULL \ |
|
77 : realloc((p), (n) ? (n) : 1)) |
|
78 #define PyMem_FREE free |
|
79 |
|
80 #endif /* PYMALLOC_DEBUG */ |
|
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 ( ((n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \ |
|
94 ( (type *) PyMem_Malloc((n) * sizeof(type)) ) ) |
|
95 #define PyMem_NEW(type, n) \ |
|
96 ( ((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) = ((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) = ((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 #ifdef __cplusplus |
|
119 } |
|
120 #endif |
|
121 |
|
122 #endif /* !Py_PYMEM_H */ |