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