]>
Commit | Line | Data |
---|---|---|
c8042e10 DM |
1 | /* The PyMem_ family: low-level memory allocation interfaces.\r |
2 | See objimpl.h for the PyObject_ memory family.\r | |
3 | */\r | |
4 | \r | |
5 | #ifndef Py_PYMEM_H\r | |
6 | #define Py_PYMEM_H\r | |
7 | \r | |
8 | #include "pyport.h"\r | |
9 | \r | |
10 | #ifdef __cplusplus\r | |
11 | extern "C" {\r | |
12 | #endif\r | |
13 | \r | |
14 | /* BEWARE:\r | |
15 | \r | |
16 | Each interface exports both functions and macros. Extension modules should\r | |
17 | use the functions, to ensure binary compatibility across Python versions.\r | |
18 | Because the Python implementation is free to change internal details, and\r | |
19 | the macros may (or may not) expose details for speed, if you do use the\r | |
20 | macros you must recompile your extensions with each Python release.\r | |
21 | \r | |
22 | Never mix calls to PyMem_ with calls to the platform malloc/realloc/\r | |
23 | calloc/free. For example, on Windows different DLLs may end up using\r | |
24 | different heaps, and if you use PyMem_Malloc you'll get the memory from the\r | |
25 | heap used by the Python DLL; it could be a disaster if you free()'ed that\r | |
26 | directly in your own extension. Using PyMem_Free instead ensures Python\r | |
27 | can return the memory to the proper heap. As another example, in\r | |
28 | PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_\r | |
29 | memory functions in special debugging wrappers that add additional\r | |
30 | debugging info to dynamic memory blocks. The system routines have no idea\r | |
31 | what to do with that stuff, and the Python wrappers have no idea what to do\r | |
32 | with raw blocks obtained directly by the system routines then.\r | |
33 | \r | |
34 | The GIL must be held when using these APIs.\r | |
35 | */\r | |
36 | \r | |
37 | /*\r | |
38 | * Raw memory interface\r | |
39 | * ====================\r | |
40 | */\r | |
41 | \r | |
42 | /* Functions\r | |
43 | \r | |
44 | Functions supplying platform-independent semantics for malloc/realloc/\r | |
45 | free. These functions make sure that allocating 0 bytes returns a distinct\r | |
46 | non-NULL pointer (whenever possible -- if we're flat out of memory, NULL\r | |
47 | may be returned), even if the platform malloc and realloc don't.\r | |
48 | Returned pointers must be checked for NULL explicitly. No action is\r | |
49 | performed on failure (no exception is set, no warning is printed, etc).\r | |
50 | */\r | |
51 | \r | |
52 | PyAPI_FUNC(void *) PyMem_Malloc(size_t);\r | |
53 | PyAPI_FUNC(void *) PyMem_Realloc(void *, size_t);\r | |
54 | PyAPI_FUNC(void) PyMem_Free(void *);\r | |
55 | \r | |
56 | /* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are\r | |
57 | no longer supported. They used to call PyErr_NoMemory() on failure. */\r | |
58 | \r | |
59 | /* Macros. */\r | |
60 | #ifdef PYMALLOC_DEBUG\r | |
61 | /* Redirect all memory operations to Python's debugging allocator. */\r | |
62 | #define PyMem_MALLOC _PyMem_DebugMalloc\r | |
63 | #define PyMem_REALLOC _PyMem_DebugRealloc\r | |
64 | #define PyMem_FREE _PyMem_DebugFree\r | |
65 | \r | |
66 | #else /* ! PYMALLOC_DEBUG */\r | |
67 | \r | |
68 | /* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL\r | |
69 | for malloc(0), which would be treated as an error. Some platforms\r | |
70 | would return a pointer with no memory behind it, which would break\r | |
71 | pymalloc. To solve these problems, allocate an extra byte. */\r | |
72 | /* Returns NULL to indicate error if a negative size or size larger than\r | |
73 | Py_ssize_t can represent is supplied. Helps prevents security holes. */\r | |
74 | #define PyMem_MALLOC(n) ((size_t)(n) > (size_t)PY_SSIZE_T_MAX ? NULL \\r | |
75 | : malloc((n) ? (n) : 1))\r | |
76 | #define PyMem_REALLOC(p, n) ((size_t)(n) > (size_t)PY_SSIZE_T_MAX ? NULL \\r | |
77 | : realloc((p), (n) ? (n) : 1))\r | |
78 | #define PyMem_FREE free\r | |
79 | \r | |
80 | #endif /* PYMALLOC_DEBUG */\r | |
81 | \r | |
82 | /*\r | |
83 | * Type-oriented memory interface\r | |
84 | * ==============================\r | |
85 | *\r | |
86 | * Allocate memory for n objects of the given type. Returns a new pointer\r | |
87 | * or NULL if the request was too large or memory allocation failed. Use\r | |
88 | * these macros rather than doing the multiplication yourself so that proper\r | |
89 | * overflow checking is always done.\r | |
90 | */\r | |
91 | \r | |
92 | #define PyMem_New(type, n) \\r | |
93 | ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \\r | |
94 | ( (type *) PyMem_Malloc((n) * sizeof(type)) ) )\r | |
95 | #define PyMem_NEW(type, n) \\r | |
96 | ( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \\r | |
97 | ( (type *) PyMem_MALLOC((n) * sizeof(type)) ) )\r | |
98 | \r | |
99 | /*\r | |
100 | * The value of (p) is always clobbered by this macro regardless of success.\r | |
101 | * The caller MUST check if (p) is NULL afterwards and deal with the memory\r | |
102 | * error if so. This means the original value of (p) MUST be saved for the\r | |
103 | * caller's memory error handler to not lose track of it.\r | |
104 | */\r | |
105 | #define PyMem_Resize(p, type, n) \\r | |
106 | ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \\r | |
107 | (type *) PyMem_Realloc((p), (n) * sizeof(type)) )\r | |
108 | #define PyMem_RESIZE(p, type, n) \\r | |
109 | ( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \\r | |
110 | (type *) PyMem_REALLOC((p), (n) * sizeof(type)) )\r | |
111 | \r | |
112 | /* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used\r | |
113 | * anymore. They're just confusing aliases for PyMem_{Free,FREE} now.\r | |
114 | */\r | |
115 | #define PyMem_Del PyMem_Free\r | |
116 | #define PyMem_DEL PyMem_FREE\r | |
117 | \r | |
118 | #ifdef __cplusplus\r | |
119 | }\r | |
120 | #endif\r | |
121 | \r | |
122 | #endif /* !Py_PYMEM_H */\r |