]>
Commit | Line | Data |
---|---|---|
c8042e10 DM |
1 | /* The PyObject_ memory family: high-level object memory interfaces.\r |
2 | See pymem.h for the low-level PyMem_ family.\r | |
3 | */\r | |
4 | \r | |
5 | #ifndef Py_OBJIMPL_H\r | |
6 | #define Py_OBJIMPL_H\r | |
7 | \r | |
8 | #include "pymem.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 PyObject_ memory functions with calls to the platform\r | |
23 | malloc/realloc/ calloc/free, or with calls to PyMem_.\r | |
24 | */\r | |
25 | \r | |
26 | /*\r | |
27 | Functions and macros for modules that implement new object types.\r | |
28 | \r | |
29 | - PyObject_New(type, typeobj) allocates memory for a new object of the given\r | |
30 | type, and initializes part of it. 'type' must be the C structure type used\r | |
31 | to represent the object, and 'typeobj' the address of the corresponding\r | |
32 | type object. Reference count and type pointer are filled in; the rest of\r | |
33 | the bytes of the object are *undefined*! The resulting expression type is\r | |
34 | 'type *'. The size of the object is determined by the tp_basicsize field\r | |
35 | of the type object.\r | |
36 | \r | |
37 | - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size\r | |
38 | object with room for n items. In addition to the refcount and type pointer\r | |
39 | fields, this also fills in the ob_size field.\r | |
40 | \r | |
41 | - PyObject_Del(op) releases the memory allocated for an object. It does not\r | |
42 | run a destructor -- it only frees the memory. PyObject_Free is identical.\r | |
43 | \r | |
44 | - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't\r | |
45 | allocate memory. Instead of a 'type' parameter, they take a pointer to a\r | |
46 | new object (allocated by an arbitrary allocator), and initialize its object\r | |
47 | header fields.\r | |
48 | \r | |
49 | Note that objects created with PyObject_{New, NewVar} are allocated using the\r | |
50 | specialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is\r | |
51 | enabled. In addition, a special debugging allocator is used if PYMALLOC_DEBUG\r | |
52 | is also #defined.\r | |
53 | \r | |
54 | In case a specific form of memory management is needed (for example, if you\r | |
55 | must use the platform malloc heap(s), or shared memory, or C++ local storage or\r | |
56 | operator new), you must first allocate the object with your custom allocator,\r | |
57 | then pass its pointer to PyObject_{Init, InitVar} for filling in its Python-\r | |
58 | specific fields: reference count, type pointer, possibly others. You should\r | |
59 | be aware that Python no control over these objects because they don't\r | |
60 | cooperate with the Python memory manager. Such objects may not be eligible\r | |
61 | for automatic garbage collection and you have to make sure that they are\r | |
62 | released accordingly whenever their destructor gets called (cf. the specific\r | |
63 | form of memory management you're using).\r | |
64 | \r | |
65 | Unless you have specific memory management requirements, use\r | |
66 | PyObject_{New, NewVar, Del}.\r | |
67 | */\r | |
68 | \r | |
69 | /*\r | |
70 | * Raw object memory interface\r | |
71 | * ===========================\r | |
72 | */\r | |
73 | \r | |
74 | /* Functions to call the same malloc/realloc/free as used by Python's\r | |
75 | object allocator. If WITH_PYMALLOC is enabled, these may differ from\r | |
76 | the platform malloc/realloc/free. The Python object allocator is\r | |
77 | designed for fast, cache-conscious allocation of many "small" objects,\r | |
78 | and with low hidden memory overhead.\r | |
79 | \r | |
80 | PyObject_Malloc(0) returns a unique non-NULL pointer if possible.\r | |
81 | \r | |
82 | PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n).\r | |
83 | PyObject_Realloc(p != NULL, 0) does not return NULL, or free the memory\r | |
84 | at p.\r | |
85 | \r | |
86 | Returned pointers must be checked for NULL explicitly; no action is\r | |
87 | performed on failure other than to return NULL (no warning it printed, no\r | |
88 | exception is set, etc).\r | |
89 | \r | |
90 | For allocating objects, use PyObject_{New, NewVar} instead whenever\r | |
91 | possible. The PyObject_{Malloc, Realloc, Free} family is exposed\r | |
92 | so that you can exploit Python's small-block allocator for non-object\r | |
93 | uses. If you must use these routines to allocate object memory, make sure\r | |
94 | the object gets initialized via PyObject_{Init, InitVar} after obtaining\r | |
95 | the raw memory.\r | |
96 | */\r | |
97 | PyAPI_FUNC(void *) PyObject_Malloc(size_t);\r | |
98 | PyAPI_FUNC(void *) PyObject_Realloc(void *, size_t);\r | |
99 | PyAPI_FUNC(void) PyObject_Free(void *);\r | |
100 | \r | |
101 | \r | |
102 | /* Macros */\r | |
103 | #ifdef WITH_PYMALLOC\r | |
104 | #ifdef PYMALLOC_DEBUG /* WITH_PYMALLOC && PYMALLOC_DEBUG */\r | |
105 | PyAPI_FUNC(void *) _PyObject_DebugMalloc(size_t nbytes);\r | |
106 | PyAPI_FUNC(void *) _PyObject_DebugRealloc(void *p, size_t nbytes);\r | |
107 | PyAPI_FUNC(void) _PyObject_DebugFree(void *p);\r | |
108 | PyAPI_FUNC(void) _PyObject_DebugDumpAddress(const void *p);\r | |
109 | PyAPI_FUNC(void) _PyObject_DebugCheckAddress(const void *p);\r | |
110 | PyAPI_FUNC(void) _PyObject_DebugMallocStats(void);\r | |
111 | PyAPI_FUNC(void *) _PyObject_DebugMallocApi(char api, size_t nbytes);\r | |
112 | PyAPI_FUNC(void *) _PyObject_DebugReallocApi(char api, void *p, size_t nbytes);\r | |
113 | PyAPI_FUNC(void) _PyObject_DebugFreeApi(char api, void *p);\r | |
114 | PyAPI_FUNC(void) _PyObject_DebugCheckAddressApi(char api, const void *p);\r | |
115 | PyAPI_FUNC(void *) _PyMem_DebugMalloc(size_t nbytes);\r | |
116 | PyAPI_FUNC(void *) _PyMem_DebugRealloc(void *p, size_t nbytes);\r | |
117 | PyAPI_FUNC(void) _PyMem_DebugFree(void *p);\r | |
118 | #define PyObject_MALLOC _PyObject_DebugMalloc\r | |
119 | #define PyObject_Malloc _PyObject_DebugMalloc\r | |
120 | #define PyObject_REALLOC _PyObject_DebugRealloc\r | |
121 | #define PyObject_Realloc _PyObject_DebugRealloc\r | |
122 | #define PyObject_FREE _PyObject_DebugFree\r | |
123 | #define PyObject_Free _PyObject_DebugFree\r | |
124 | \r | |
125 | #else /* WITH_PYMALLOC && ! PYMALLOC_DEBUG */\r | |
126 | #define PyObject_MALLOC PyObject_Malloc\r | |
127 | #define PyObject_REALLOC PyObject_Realloc\r | |
128 | #define PyObject_FREE PyObject_Free\r | |
129 | #endif\r | |
130 | \r | |
131 | #else /* ! WITH_PYMALLOC */\r | |
132 | #define PyObject_MALLOC PyMem_MALLOC\r | |
133 | #define PyObject_REALLOC PyMem_REALLOC\r | |
134 | #define PyObject_FREE PyMem_FREE\r | |
135 | \r | |
136 | #endif /* WITH_PYMALLOC */\r | |
137 | \r | |
138 | #define PyObject_Del PyObject_Free\r | |
139 | #define PyObject_DEL PyObject_FREE\r | |
140 | \r | |
141 | /* for source compatibility with 2.2 */\r | |
142 | #define _PyObject_Del PyObject_Free\r | |
143 | \r | |
144 | /*\r | |
145 | * Generic object allocator interface\r | |
146 | * ==================================\r | |
147 | */\r | |
148 | \r | |
149 | /* Functions */\r | |
150 | PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *);\r | |
151 | PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *,\r | |
152 | PyTypeObject *, Py_ssize_t);\r | |
153 | PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *);\r | |
154 | PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t);\r | |
155 | \r | |
156 | #define PyObject_New(type, typeobj) \\r | |
157 | ( (type *) _PyObject_New(typeobj) )\r | |
158 | #define PyObject_NewVar(type, typeobj, n) \\r | |
159 | ( (type *) _PyObject_NewVar((typeobj), (n)) )\r | |
160 | \r | |
161 | /* Macros trading binary compatibility for speed. See also pymem.h.\r | |
162 | Note that these macros expect non-NULL object pointers.*/\r | |
163 | #define PyObject_INIT(op, typeobj) \\r | |
164 | ( Py_TYPE(op) = (typeobj), _Py_NewReference((PyObject *)(op)), (op) )\r | |
165 | #define PyObject_INIT_VAR(op, typeobj, size) \\r | |
166 | ( Py_SIZE(op) = (size), PyObject_INIT((op), (typeobj)) )\r | |
167 | \r | |
168 | #define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize )\r | |
169 | \r | |
170 | /* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a\r | |
171 | vrbl-size object with nitems items, exclusive of gc overhead (if any). The\r | |
172 | value is rounded up to the closest multiple of sizeof(void *), in order to\r | |
173 | ensure that pointer fields at the end of the object are correctly aligned\r | |
174 | for the platform (this is of special importance for subclasses of, e.g.,\r | |
175 | str or long, so that pointers can be stored after the embedded data).\r | |
176 | \r | |
177 | Note that there's no memory wastage in doing this, as malloc has to\r | |
178 | return (at worst) pointer-aligned memory anyway.\r | |
179 | */\r | |
180 | #if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0\r | |
181 | # error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2"\r | |
182 | #endif\r | |
183 | \r | |
184 | #define _PyObject_VAR_SIZE(typeobj, nitems) \\r | |
185 | (size_t) \\r | |
186 | ( ( (typeobj)->tp_basicsize + \\r | |
187 | (nitems)*(typeobj)->tp_itemsize + \\r | |
188 | (SIZEOF_VOID_P - 1) \\r | |
189 | ) & ~(SIZEOF_VOID_P - 1) \\r | |
190 | )\r | |
191 | \r | |
192 | #define PyObject_NEW(type, typeobj) \\r | |
193 | ( (type *) PyObject_Init( \\r | |
194 | (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) )\r | |
195 | \r | |
196 | #define PyObject_NEW_VAR(type, typeobj, n) \\r | |
197 | ( (type *) PyObject_InitVar( \\r | |
198 | (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\\r | |
199 | (typeobj), (n)) )\r | |
200 | \r | |
201 | /* This example code implements an object constructor with a custom\r | |
202 | allocator, where PyObject_New is inlined, and shows the important\r | |
203 | distinction between two steps (at least):\r | |
204 | 1) the actual allocation of the object storage;\r | |
205 | 2) the initialization of the Python specific fields\r | |
206 | in this storage with PyObject_{Init, InitVar}.\r | |
207 | \r | |
208 | PyObject *\r | |
209 | YourObject_New(...)\r | |
210 | {\r | |
211 | PyObject *op;\r | |
212 | \r | |
213 | op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct));\r | |
214 | if (op == NULL)\r | |
215 | return PyErr_NoMemory();\r | |
216 | \r | |
217 | PyObject_Init(op, &YourTypeStruct);\r | |
218 | \r | |
219 | op->ob_field = value;\r | |
220 | ...\r | |
221 | return op;\r | |
222 | }\r | |
223 | \r | |
224 | Note that in C++, the use of the new operator usually implies that\r | |
225 | the 1st step is performed automatically for you, so in a C++ class\r | |
226 | constructor you would start directly with PyObject_Init/InitVar\r | |
227 | */\r | |
228 | \r | |
229 | /*\r | |
230 | * Garbage Collection Support\r | |
231 | * ==========================\r | |
232 | */\r | |
233 | \r | |
234 | /* C equivalent of gc.collect(). */\r | |
235 | PyAPI_FUNC(Py_ssize_t) PyGC_Collect(void);\r | |
236 | \r | |
237 | /* Test if a type has a GC head */\r | |
238 | #define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC)\r | |
239 | \r | |
240 | /* Test if an object has a GC head */\r | |
241 | #define PyObject_IS_GC(o) (PyType_IS_GC(Py_TYPE(o)) && \\r | |
242 | (Py_TYPE(o)->tp_is_gc == NULL || Py_TYPE(o)->tp_is_gc(o)))\r | |
243 | \r | |
244 | PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t);\r | |
245 | #define PyObject_GC_Resize(type, op, n) \\r | |
246 | ( (type *) _PyObject_GC_Resize((PyVarObject *)(op), (n)) )\r | |
247 | \r | |
248 | /* for source compatibility with 2.2 */\r | |
249 | #define _PyObject_GC_Del PyObject_GC_Del\r | |
250 | \r | |
251 | /* GC information is stored BEFORE the object structure. */\r | |
252 | typedef union _gc_head {\r | |
253 | struct {\r | |
254 | union _gc_head *gc_next;\r | |
255 | union _gc_head *gc_prev;\r | |
256 | Py_ssize_t gc_refs;\r | |
257 | } gc;\r | |
258 | long double dummy; /* force worst-case alignment */\r | |
259 | } PyGC_Head;\r | |
260 | \r | |
261 | extern PyGC_Head *_PyGC_generation0;\r | |
262 | \r | |
263 | #define _Py_AS_GC(o) ((PyGC_Head *)(o)-1)\r | |
264 | \r | |
265 | #define _PyGC_REFS_UNTRACKED (-2)\r | |
266 | #define _PyGC_REFS_REACHABLE (-3)\r | |
267 | #define _PyGC_REFS_TENTATIVELY_UNREACHABLE (-4)\r | |
268 | \r | |
269 | /* Tell the GC to track this object. NB: While the object is tracked the\r | |
270 | * collector it must be safe to call the ob_traverse method. */\r | |
271 | #define _PyObject_GC_TRACK(o) do { \\r | |
272 | PyGC_Head *g = _Py_AS_GC(o); \\r | |
273 | if (g->gc.gc_refs != _PyGC_REFS_UNTRACKED) \\r | |
274 | Py_FatalError("GC object already tracked"); \\r | |
275 | g->gc.gc_refs = _PyGC_REFS_REACHABLE; \\r | |
276 | g->gc.gc_next = _PyGC_generation0; \\r | |
277 | g->gc.gc_prev = _PyGC_generation0->gc.gc_prev; \\r | |
278 | g->gc.gc_prev->gc.gc_next = g; \\r | |
279 | _PyGC_generation0->gc.gc_prev = g; \\r | |
280 | } while (0);\r | |
281 | \r | |
282 | /* Tell the GC to stop tracking this object.\r | |
283 | * gc_next doesn't need to be set to NULL, but doing so is a good\r | |
284 | * way to provoke memory errors if calling code is confused.\r | |
285 | */\r | |
286 | #define _PyObject_GC_UNTRACK(o) do { \\r | |
287 | PyGC_Head *g = _Py_AS_GC(o); \\r | |
288 | assert(g->gc.gc_refs != _PyGC_REFS_UNTRACKED); \\r | |
289 | g->gc.gc_refs = _PyGC_REFS_UNTRACKED; \\r | |
290 | g->gc.gc_prev->gc.gc_next = g->gc.gc_next; \\r | |
291 | g->gc.gc_next->gc.gc_prev = g->gc.gc_prev; \\r | |
292 | g->gc.gc_next = NULL; \\r | |
293 | } while (0);\r | |
294 | \r | |
295 | /* True if the object is currently tracked by the GC. */\r | |
296 | #define _PyObject_GC_IS_TRACKED(o) \\r | |
297 | ((_Py_AS_GC(o))->gc.gc_refs != _PyGC_REFS_UNTRACKED)\r | |
298 | \r | |
299 | /* True if the object may be tracked by the GC in the future, or already is.\r | |
300 | This can be useful to implement some optimizations. */\r | |
301 | #define _PyObject_GC_MAY_BE_TRACKED(obj) \\r | |
302 | (PyObject_IS_GC(obj) && \\r | |
303 | (!PyTuple_CheckExact(obj) || _PyObject_GC_IS_TRACKED(obj)))\r | |
304 | \r | |
305 | \r | |
306 | PyAPI_FUNC(PyObject *) _PyObject_GC_Malloc(size_t);\r | |
307 | PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *);\r | |
308 | PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t);\r | |
309 | PyAPI_FUNC(void) PyObject_GC_Track(void *);\r | |
310 | PyAPI_FUNC(void) PyObject_GC_UnTrack(void *);\r | |
311 | PyAPI_FUNC(void) PyObject_GC_Del(void *);\r | |
312 | \r | |
313 | #define PyObject_GC_New(type, typeobj) \\r | |
314 | ( (type *) _PyObject_GC_New(typeobj) )\r | |
315 | #define PyObject_GC_NewVar(type, typeobj, n) \\r | |
316 | ( (type *) _PyObject_GC_NewVar((typeobj), (n)) )\r | |
317 | \r | |
318 | \r | |
319 | /* Utility macro to help write tp_traverse functions.\r | |
320 | * To use this macro, the tp_traverse function must name its arguments\r | |
321 | * "visit" and "arg". This is intended to keep tp_traverse functions\r | |
322 | * looking as much alike as possible.\r | |
323 | */\r | |
324 | #define Py_VISIT(op) \\r | |
325 | do { \\r | |
326 | if (op) { \\r | |
327 | int vret = visit((PyObject *)(op), arg); \\r | |
328 | if (vret) \\r | |
329 | return vret; \\r | |
330 | } \\r | |
331 | } while (0)\r | |
332 | \r | |
333 | /* This is here for the sake of backwards compatibility. Extensions that\r | |
334 | * use the old GC API will still compile but the objects will not be\r | |
335 | * tracked by the GC. */\r | |
336 | #define PyGC_HEAD_SIZE 0\r | |
337 | #define PyObject_GC_Init(op)\r | |
338 | #define PyObject_GC_Fini(op)\r | |
339 | #define PyObject_AS_GC(op) (op)\r | |
340 | #define PyObject_FROM_GC(op) (op)\r | |
341 | \r | |
342 | \r | |
343 | /* Test if a type supports weak references */\r | |
344 | #define PyType_SUPPORTS_WEAKREFS(t) \\r | |
345 | (PyType_HasFeature((t), Py_TPFLAGS_HAVE_WEAKREFS) \\r | |
346 | && ((t)->tp_weaklistoffset > 0))\r | |
347 | \r | |
348 | #define PyObject_GET_WEAKREFS_LISTPTR(o) \\r | |
349 | ((PyObject **) (((char *) (o)) + Py_TYPE(o)->tp_weaklistoffset))\r | |
350 | \r | |
351 | #ifdef __cplusplus\r | |
352 | }\r | |
353 | #endif\r | |
354 | #endif /* !Py_OBJIMPL_H */\r |