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