|
1 #ifndef Py_OBJECT_H |
|
2 #define Py_OBJECT_H |
|
3 #ifdef __cplusplus |
|
4 extern "C" { |
|
5 #endif |
|
6 |
|
7 |
|
8 /* Object and type object interface */ |
|
9 |
|
10 /* |
|
11 Objects are structures allocated on the heap. Special rules apply to |
|
12 the use of objects to ensure they are properly garbage-collected. |
|
13 Objects are never allocated statically or on the stack; they must be |
|
14 accessed through special macros and functions only. (Type objects are |
|
15 exceptions to the first rule; the standard types are represented by |
|
16 statically initialized type objects, although work on type/class unification |
|
17 for Python 2.2 made it possible to have heap-allocated type objects too). |
|
18 |
|
19 An object has a 'reference count' that is increased or decreased when a |
|
20 pointer to the object is copied or deleted; when the reference count |
|
21 reaches zero there are no references to the object left and it can be |
|
22 removed from the heap. |
|
23 |
|
24 An object has a 'type' that determines what it represents and what kind |
|
25 of data it contains. An object's type is fixed when it is created. |
|
26 Types themselves are represented as objects; an object contains a |
|
27 pointer to the corresponding type object. The type itself has a type |
|
28 pointer pointing to the object representing the type 'type', which |
|
29 contains a pointer to itself!). |
|
30 |
|
31 Objects do not float around in memory; once allocated an object keeps |
|
32 the same size and address. Objects that must hold variable-size data |
|
33 can contain pointers to variable-size parts of the object. Not all |
|
34 objects of the same type have the same size; but the size cannot change |
|
35 after allocation. (These restrictions are made so a reference to an |
|
36 object can be simply a pointer -- moving an object would require |
|
37 updating all the pointers, and changing an object's size would require |
|
38 moving it if there was another object right next to it.) |
|
39 |
|
40 Objects are always accessed through pointers of the type 'PyObject *'. |
|
41 The type 'PyObject' is a structure that only contains the reference count |
|
42 and the type pointer. The actual memory allocated for an object |
|
43 contains other data that can only be accessed after casting the pointer |
|
44 to a pointer to a longer structure type. This longer type must start |
|
45 with the reference count and type fields; the macro PyObject_HEAD should be |
|
46 used for this (to accommodate for future changes). The implementation |
|
47 of a particular object type can cast the object pointer to the proper |
|
48 type and back. |
|
49 |
|
50 A standard interface exists for objects that contain an array of items |
|
51 whose size is determined when the object is allocated. |
|
52 */ |
|
53 |
|
54 /* Py_DEBUG implies Py_TRACE_REFS. */ |
|
55 #if defined(Py_DEBUG) && !defined(Py_TRACE_REFS) |
|
56 #define Py_TRACE_REFS |
|
57 #endif |
|
58 |
|
59 /* Py_TRACE_REFS implies Py_REF_DEBUG. */ |
|
60 #if defined(Py_TRACE_REFS) && !defined(Py_REF_DEBUG) |
|
61 #define Py_REF_DEBUG |
|
62 #endif |
|
63 |
|
64 #ifdef Py_TRACE_REFS |
|
65 /* Define pointers to support a doubly-linked list of all live heap objects. */ |
|
66 #define _PyObject_HEAD_EXTRA \ |
|
67 struct _object *_ob_next; \ |
|
68 struct _object *_ob_prev; |
|
69 |
|
70 #define _PyObject_EXTRA_INIT 0, 0, |
|
71 |
|
72 #else |
|
73 #define _PyObject_HEAD_EXTRA |
|
74 #define _PyObject_EXTRA_INIT |
|
75 #endif |
|
76 |
|
77 /* PyObject_HEAD defines the initial segment of every PyObject. */ |
|
78 #define PyObject_HEAD \ |
|
79 _PyObject_HEAD_EXTRA \ |
|
80 Py_ssize_t ob_refcnt; \ |
|
81 struct _typeobject *ob_type; |
|
82 |
|
83 #define PyObject_HEAD_INIT(type) \ |
|
84 _PyObject_EXTRA_INIT \ |
|
85 1, type, |
|
86 |
|
87 #define PyVarObject_HEAD_INIT(type, size) \ |
|
88 PyObject_HEAD_INIT(type) size, |
|
89 |
|
90 /* PyObject_VAR_HEAD defines the initial segment of all variable-size |
|
91 * container objects. These end with a declaration of an array with 1 |
|
92 * element, but enough space is malloc'ed so that the array actually |
|
93 * has room for ob_size elements. Note that ob_size is an element count, |
|
94 * not necessarily a byte count. |
|
95 */ |
|
96 #define PyObject_VAR_HEAD \ |
|
97 PyObject_HEAD \ |
|
98 Py_ssize_t ob_size; /* Number of items in variable part */ |
|
99 #define Py_INVALID_SIZE (Py_ssize_t)-1 |
|
100 |
|
101 /* Nothing is actually declared to be a PyObject, but every pointer to |
|
102 * a Python object can be cast to a PyObject*. This is inheritance built |
|
103 * by hand. Similarly every pointer to a variable-size Python object can, |
|
104 * in addition, be cast to PyVarObject*. |
|
105 */ |
|
106 typedef struct _object { |
|
107 PyObject_HEAD |
|
108 } PyObject; |
|
109 |
|
110 typedef struct { |
|
111 PyObject_VAR_HEAD |
|
112 } PyVarObject; |
|
113 |
|
114 #define Py_REFCNT(ob) (((PyObject*)(ob))->ob_refcnt) |
|
115 #define Py_TYPE(ob) (((PyObject*)(ob))->ob_type) |
|
116 #define Py_SIZE(ob) (((PyVarObject*)(ob))->ob_size) |
|
117 |
|
118 /* |
|
119 Type objects contain a string containing the type name (to help somewhat |
|
120 in debugging), the allocation parameters (see PyObject_New() and |
|
121 PyObject_NewVar()), |
|
122 and methods for accessing objects of the type. Methods are optional, a |
|
123 nil pointer meaning that particular kind of access is not available for |
|
124 this type. The Py_DECREF() macro uses the tp_dealloc method without |
|
125 checking for a nil pointer; it should always be implemented except if |
|
126 the implementation can guarantee that the reference count will never |
|
127 reach zero (e.g., for statically allocated type objects). |
|
128 |
|
129 NB: the methods for certain type groups are now contained in separate |
|
130 method blocks. |
|
131 */ |
|
132 |
|
133 typedef PyObject * (*unaryfunc)(PyObject *); |
|
134 typedef PyObject * (*binaryfunc)(PyObject *, PyObject *); |
|
135 typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *); |
|
136 typedef int (*inquiry)(PyObject *); |
|
137 typedef Py_ssize_t (*lenfunc)(PyObject *); |
|
138 typedef int (*coercion)(PyObject **, PyObject **); |
|
139 typedef PyObject *(*intargfunc)(PyObject *, int) Py_DEPRECATED(2.5); |
|
140 typedef PyObject *(*intintargfunc)(PyObject *, int, int) Py_DEPRECATED(2.5); |
|
141 typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t); |
|
142 typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t); |
|
143 typedef int(*intobjargproc)(PyObject *, int, PyObject *); |
|
144 typedef int(*intintobjargproc)(PyObject *, int, int, PyObject *); |
|
145 typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *); |
|
146 typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *); |
|
147 typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *); |
|
148 |
|
149 |
|
150 |
|
151 /* int-based buffer interface */ |
|
152 typedef int (*getreadbufferproc)(PyObject *, int, void **); |
|
153 typedef int (*getwritebufferproc)(PyObject *, int, void **); |
|
154 typedef int (*getsegcountproc)(PyObject *, int *); |
|
155 typedef int (*getcharbufferproc)(PyObject *, int, char **); |
|
156 /* ssize_t-based buffer interface */ |
|
157 typedef Py_ssize_t (*readbufferproc)(PyObject *, Py_ssize_t, void **); |
|
158 typedef Py_ssize_t (*writebufferproc)(PyObject *, Py_ssize_t, void **); |
|
159 typedef Py_ssize_t (*segcountproc)(PyObject *, Py_ssize_t *); |
|
160 typedef Py_ssize_t (*charbufferproc)(PyObject *, Py_ssize_t, char **); |
|
161 |
|
162 /* Py3k buffer interface */ |
|
163 |
|
164 typedef struct bufferinfo { |
|
165 void *buf; |
|
166 PyObject *obj; /* borrowed reference */ |
|
167 Py_ssize_t len; |
|
168 Py_ssize_t itemsize; /* This is Py_ssize_t so it can be |
|
169 pointed to by strides in simple case.*/ |
|
170 int readonly; |
|
171 int ndim; |
|
172 char *format; |
|
173 Py_ssize_t *shape; |
|
174 Py_ssize_t *strides; |
|
175 Py_ssize_t *suboffsets; |
|
176 void *internal; |
|
177 } Py_buffer; |
|
178 |
|
179 typedef int (*getbufferproc)(PyObject *, Py_buffer *, int); |
|
180 typedef void (*releasebufferproc)(PyObject *, Py_buffer *); |
|
181 |
|
182 /* Flags for getting buffers */ |
|
183 #define PyBUF_SIMPLE 0 |
|
184 #define PyBUF_WRITABLE 0x0001 |
|
185 /* we used to include an E, backwards compatible alias */ |
|
186 #define PyBUF_WRITEABLE PyBUF_WRITABLE |
|
187 #define PyBUF_FORMAT 0x0004 |
|
188 #define PyBUF_ND 0x0008 |
|
189 #define PyBUF_STRIDES (0x0010 | PyBUF_ND) |
|
190 #define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES) |
|
191 #define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES) |
|
192 #define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES) |
|
193 #define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES) |
|
194 |
|
195 #define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE) |
|
196 #define PyBUF_CONTIG_RO (PyBUF_ND) |
|
197 |
|
198 #define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE) |
|
199 #define PyBUF_STRIDED_RO (PyBUF_STRIDES) |
|
200 |
|
201 #define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT) |
|
202 #define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT) |
|
203 |
|
204 #define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT) |
|
205 #define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT) |
|
206 |
|
207 |
|
208 #define PyBUF_READ 0x100 |
|
209 #define PyBUF_WRITE 0x200 |
|
210 #define PyBUF_SHADOW 0x400 |
|
211 /* end Py3k buffer interface */ |
|
212 |
|
213 typedef int (*objobjproc)(PyObject *, PyObject *); |
|
214 typedef int (*visitproc)(PyObject *, void *); |
|
215 typedef int (*traverseproc)(PyObject *, visitproc, void *); |
|
216 |
|
217 typedef struct { |
|
218 /* For numbers without flag bit Py_TPFLAGS_CHECKTYPES set, all |
|
219 arguments are guaranteed to be of the object's type (modulo |
|
220 coercion hacks -- i.e. if the type's coercion function |
|
221 returns other types, then these are allowed as well). Numbers that |
|
222 have the Py_TPFLAGS_CHECKTYPES flag bit set should check *both* |
|
223 arguments for proper type and implement the necessary conversions |
|
224 in the slot functions themselves. */ |
|
225 |
|
226 binaryfunc nb_add; |
|
227 binaryfunc nb_subtract; |
|
228 binaryfunc nb_multiply; |
|
229 binaryfunc nb_divide; |
|
230 binaryfunc nb_remainder; |
|
231 binaryfunc nb_divmod; |
|
232 ternaryfunc nb_power; |
|
233 unaryfunc nb_negative; |
|
234 unaryfunc nb_positive; |
|
235 unaryfunc nb_absolute; |
|
236 inquiry nb_nonzero; |
|
237 unaryfunc nb_invert; |
|
238 binaryfunc nb_lshift; |
|
239 binaryfunc nb_rshift; |
|
240 binaryfunc nb_and; |
|
241 binaryfunc nb_xor; |
|
242 binaryfunc nb_or; |
|
243 coercion nb_coerce; |
|
244 unaryfunc nb_int; |
|
245 unaryfunc nb_long; |
|
246 unaryfunc nb_float; |
|
247 unaryfunc nb_oct; |
|
248 unaryfunc nb_hex; |
|
249 /* Added in release 2.0 */ |
|
250 binaryfunc nb_inplace_add; |
|
251 binaryfunc nb_inplace_subtract; |
|
252 binaryfunc nb_inplace_multiply; |
|
253 binaryfunc nb_inplace_divide; |
|
254 binaryfunc nb_inplace_remainder; |
|
255 ternaryfunc nb_inplace_power; |
|
256 binaryfunc nb_inplace_lshift; |
|
257 binaryfunc nb_inplace_rshift; |
|
258 binaryfunc nb_inplace_and; |
|
259 binaryfunc nb_inplace_xor; |
|
260 binaryfunc nb_inplace_or; |
|
261 |
|
262 /* Added in release 2.2 */ |
|
263 /* The following require the Py_TPFLAGS_HAVE_CLASS flag */ |
|
264 binaryfunc nb_floor_divide; |
|
265 binaryfunc nb_true_divide; |
|
266 binaryfunc nb_inplace_floor_divide; |
|
267 binaryfunc nb_inplace_true_divide; |
|
268 |
|
269 /* Added in release 2.5 */ |
|
270 unaryfunc nb_index; |
|
271 } PyNumberMethods; |
|
272 |
|
273 typedef struct { |
|
274 lenfunc sq_length; |
|
275 binaryfunc sq_concat; |
|
276 ssizeargfunc sq_repeat; |
|
277 ssizeargfunc sq_item; |
|
278 ssizessizeargfunc sq_slice; |
|
279 ssizeobjargproc sq_ass_item; |
|
280 ssizessizeobjargproc sq_ass_slice; |
|
281 objobjproc sq_contains; |
|
282 /* Added in release 2.0 */ |
|
283 binaryfunc sq_inplace_concat; |
|
284 ssizeargfunc sq_inplace_repeat; |
|
285 } PySequenceMethods; |
|
286 |
|
287 typedef struct { |
|
288 lenfunc mp_length; |
|
289 binaryfunc mp_subscript; |
|
290 objobjargproc mp_ass_subscript; |
|
291 } PyMappingMethods; |
|
292 |
|
293 typedef struct { |
|
294 readbufferproc bf_getreadbuffer; |
|
295 writebufferproc bf_getwritebuffer; |
|
296 segcountproc bf_getsegcount; |
|
297 charbufferproc bf_getcharbuffer; |
|
298 getbufferproc bf_getbuffer; |
|
299 releasebufferproc bf_releasebuffer; |
|
300 } PyBufferProcs; |
|
301 |
|
302 |
|
303 typedef void (*freefunc)(void *); |
|
304 typedef void (*destructor)(PyObject *); |
|
305 typedef int (*printfunc)(PyObject *, FILE *, int); |
|
306 typedef PyObject *(*getattrfunc)(PyObject *, char *); |
|
307 typedef PyObject *(*getattrofunc)(PyObject *, PyObject *); |
|
308 typedef int (*setattrfunc)(PyObject *, char *, PyObject *); |
|
309 typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *); |
|
310 typedef int (*cmpfunc)(PyObject *, PyObject *); |
|
311 typedef PyObject *(*reprfunc)(PyObject *); |
|
312 typedef long (*hashfunc)(PyObject *); |
|
313 typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int); |
|
314 typedef PyObject *(*getiterfunc) (PyObject *); |
|
315 typedef PyObject *(*iternextfunc) (PyObject *); |
|
316 typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *); |
|
317 typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *); |
|
318 typedef int (*initproc)(PyObject *, PyObject *, PyObject *); |
|
319 typedef PyObject *(*newfunc)(struct _typeobject *, PyObject *, PyObject *); |
|
320 typedef PyObject *(*allocfunc)(struct _typeobject *, Py_ssize_t); |
|
321 |
|
322 typedef struct _typeobject { |
|
323 PyObject_VAR_HEAD |
|
324 const char *tp_name; /* For printing, in format "<module>.<name>" */ |
|
325 Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */ |
|
326 |
|
327 /* Methods to implement standard operations */ |
|
328 |
|
329 destructor tp_dealloc; |
|
330 printfunc tp_print; |
|
331 getattrfunc tp_getattr; |
|
332 setattrfunc tp_setattr; |
|
333 cmpfunc tp_compare; |
|
334 reprfunc tp_repr; |
|
335 |
|
336 /* Method suites for standard classes */ |
|
337 |
|
338 PyNumberMethods *tp_as_number; |
|
339 PySequenceMethods *tp_as_sequence; |
|
340 PyMappingMethods *tp_as_mapping; |
|
341 |
|
342 /* More standard operations (here for binary compatibility) */ |
|
343 |
|
344 hashfunc tp_hash; |
|
345 ternaryfunc tp_call; |
|
346 reprfunc tp_str; |
|
347 getattrofunc tp_getattro; |
|
348 setattrofunc tp_setattro; |
|
349 |
|
350 /* Functions to access object as input/output buffer */ |
|
351 PyBufferProcs *tp_as_buffer; |
|
352 |
|
353 /* Flags to define presence of optional/expanded features */ |
|
354 long tp_flags; |
|
355 |
|
356 const char *tp_doc; /* Documentation string */ |
|
357 |
|
358 /* Assigned meaning in release 2.0 */ |
|
359 /* call function for all accessible objects */ |
|
360 traverseproc tp_traverse; |
|
361 |
|
362 /* delete references to contained objects */ |
|
363 inquiry tp_clear; |
|
364 |
|
365 /* Assigned meaning in release 2.1 */ |
|
366 /* rich comparisons */ |
|
367 richcmpfunc tp_richcompare; |
|
368 |
|
369 /* weak reference enabler */ |
|
370 Py_ssize_t tp_weaklistoffset; |
|
371 |
|
372 /* Added in release 2.2 */ |
|
373 /* Iterators */ |
|
374 getiterfunc tp_iter; |
|
375 iternextfunc tp_iternext; |
|
376 |
|
377 /* Attribute descriptor and subclassing stuff */ |
|
378 struct PyMethodDef *tp_methods; |
|
379 struct PyMemberDef *tp_members; |
|
380 struct PyGetSetDef *tp_getset; |
|
381 struct _typeobject *tp_base; |
|
382 PyObject *tp_dict; |
|
383 descrgetfunc tp_descr_get; |
|
384 descrsetfunc tp_descr_set; |
|
385 Py_ssize_t tp_dictoffset; |
|
386 initproc tp_init; |
|
387 allocfunc tp_alloc; |
|
388 newfunc tp_new; |
|
389 freefunc tp_free; /* Low-level free-memory routine */ |
|
390 inquiry tp_is_gc; /* For PyObject_IS_GC */ |
|
391 PyObject *tp_bases; |
|
392 PyObject *tp_mro; /* method resolution order */ |
|
393 PyObject *tp_cache; |
|
394 PyObject *tp_subclasses; |
|
395 PyObject *tp_weaklist; |
|
396 destructor tp_del; |
|
397 |
|
398 /* Type attribute cache version tag. Added in version 2.6 */ |
|
399 unsigned int tp_version_tag; |
|
400 |
|
401 #ifdef COUNT_ALLOCS |
|
402 /* these must be last and never explicitly initialized */ |
|
403 Py_ssize_t tp_allocs; |
|
404 Py_ssize_t tp_frees; |
|
405 Py_ssize_t tp_maxalloc; |
|
406 struct _typeobject *tp_prev; |
|
407 struct _typeobject *tp_next; |
|
408 #endif |
|
409 } PyTypeObject; |
|
410 |
|
411 |
|
412 /* The *real* layout of a type object when allocated on the heap */ |
|
413 typedef struct _heaptypeobject { |
|
414 /* Note: there's a dependency on the order of these members |
|
415 in slotptr() in typeobject.c . */ |
|
416 PyTypeObject ht_type; |
|
417 PyNumberMethods as_number; |
|
418 PyMappingMethods as_mapping; |
|
419 PySequenceMethods as_sequence; /* as_sequence comes after as_mapping, |
|
420 so that the mapping wins when both |
|
421 the mapping and the sequence define |
|
422 a given operator (e.g. __getitem__). |
|
423 see add_operators() in typeobject.c . */ |
|
424 PyBufferProcs as_buffer; |
|
425 PyObject *ht_name, *ht_slots; |
|
426 /* here are optional user slots, followed by the members. */ |
|
427 } PyHeapTypeObject; |
|
428 |
|
429 /* access macro to the members which are floating "behind" the object */ |
|
430 #define PyHeapType_GET_MEMBERS(etype) \ |
|
431 ((PyMemberDef *)(((char *)etype) + Py_TYPE(etype)->tp_basicsize)) |
|
432 |
|
433 |
|
434 /* Generic type check */ |
|
435 PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *); |
|
436 #define PyObject_TypeCheck(ob, tp) \ |
|
437 (Py_TYPE(ob) == (tp) || PyType_IsSubtype(Py_TYPE(ob), (tp))) |
|
438 |
|
439 PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */ |
|
440 PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */ |
|
441 PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */ |
|
442 |
|
443 #define PyType_Check(op) \ |
|
444 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS) |
|
445 #define PyType_CheckExact(op) (Py_TYPE(op) == &PyType_Type) |
|
446 |
|
447 PyAPI_FUNC(int) PyType_Ready(PyTypeObject *); |
|
448 PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t); |
|
449 PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *, |
|
450 PyObject *, PyObject *); |
|
451 PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *); |
|
452 PyAPI_FUNC(unsigned int) PyType_ClearCache(void); |
|
453 PyAPI_FUNC(void) PyType_Modified(PyTypeObject *); |
|
454 |
|
455 /* Generic operations on objects */ |
|
456 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int); |
|
457 PyAPI_FUNC(void) _PyObject_Dump(PyObject *); |
|
458 PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *); |
|
459 PyAPI_FUNC(PyObject *) _PyObject_Str(PyObject *); |
|
460 PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *); |
|
461 #define PyObject_Bytes PyObject_Str |
|
462 #ifdef Py_USING_UNICODE |
|
463 PyAPI_FUNC(PyObject *) PyObject_Unicode(PyObject *); |
|
464 #endif |
|
465 PyAPI_FUNC(int) PyObject_Compare(PyObject *, PyObject *); |
|
466 PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int); |
|
467 PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int); |
|
468 PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *); |
|
469 PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *); |
|
470 PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *); |
|
471 PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *); |
|
472 PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *); |
|
473 PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *); |
|
474 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *); |
|
475 PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *); |
|
476 PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *); |
|
477 PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, |
|
478 PyObject *, PyObject *); |
|
479 PyAPI_FUNC(long) PyObject_Hash(PyObject *); |
|
480 PyAPI_FUNC(long) PyObject_HashNotImplemented(PyObject *); |
|
481 PyAPI_FUNC(int) PyObject_IsTrue(PyObject *); |
|
482 PyAPI_FUNC(int) PyObject_Not(PyObject *); |
|
483 PyAPI_FUNC(int) PyCallable_Check(PyObject *); |
|
484 PyAPI_FUNC(int) PyNumber_Coerce(PyObject **, PyObject **); |
|
485 PyAPI_FUNC(int) PyNumber_CoerceEx(PyObject **, PyObject **); |
|
486 |
|
487 PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *); |
|
488 |
|
489 /* A slot function whose address we need to compare */ |
|
490 extern int _PyObject_SlotCompare(PyObject *, PyObject *); |
|
491 |
|
492 |
|
493 /* PyObject_Dir(obj) acts like Python __builtin__.dir(obj), returning a |
|
494 list of strings. PyObject_Dir(NULL) is like __builtin__.dir(), |
|
495 returning the names of the current locals. In this case, if there are |
|
496 no current locals, NULL is returned, and PyErr_Occurred() is false. |
|
497 */ |
|
498 PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *); |
|
499 |
|
500 |
|
501 /* Helpers for printing recursive container types */ |
|
502 PyAPI_FUNC(int) Py_ReprEnter(PyObject *); |
|
503 PyAPI_FUNC(void) Py_ReprLeave(PyObject *); |
|
504 |
|
505 /* Helpers for hash functions */ |
|
506 PyAPI_FUNC(long) _Py_HashDouble(double); |
|
507 PyAPI_FUNC(long) _Py_HashPointer(void*); |
|
508 |
|
509 /* Helper for passing objects to printf and the like */ |
|
510 #define PyObject_REPR(obj) PyString_AS_STRING(PyObject_Repr(obj)) |
|
511 |
|
512 /* Flag bits for printing: */ |
|
513 #define Py_PRINT_RAW 1 /* No string quotes etc. */ |
|
514 |
|
515 /* |
|
516 `Type flags (tp_flags) |
|
517 |
|
518 These flags are used to extend the type structure in a backwards-compatible |
|
519 fashion. Extensions can use the flags to indicate (and test) when a given |
|
520 type structure contains a new feature. The Python core will use these when |
|
521 introducing new functionality between major revisions (to avoid mid-version |
|
522 changes in the PYTHON_API_VERSION). |
|
523 |
|
524 Arbitration of the flag bit positions will need to be coordinated among |
|
525 all extension writers who publically release their extensions (this will |
|
526 be fewer than you might expect!).. |
|
527 |
|
528 Python 1.5.2 introduced the bf_getcharbuffer slot into PyBufferProcs. |
|
529 |
|
530 Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value. |
|
531 |
|
532 Code can use PyType_HasFeature(type_ob, flag_value) to test whether the |
|
533 given type object has a specified feature. |
|
534 |
|
535 NOTE: when building the core, Py_TPFLAGS_DEFAULT includes |
|
536 Py_TPFLAGS_HAVE_VERSION_TAG; outside the core, it doesn't. This is so |
|
537 that extensions that modify tp_dict of their own types directly don't |
|
538 break, since this was allowed in 2.5. In 3.0 they will have to |
|
539 manually remove this flag though! |
|
540 */ |
|
541 |
|
542 /* PyBufferProcs contains bf_getcharbuffer */ |
|
543 #define Py_TPFLAGS_HAVE_GETCHARBUFFER (1L<<0) |
|
544 |
|
545 /* PySequenceMethods contains sq_contains */ |
|
546 #define Py_TPFLAGS_HAVE_SEQUENCE_IN (1L<<1) |
|
547 |
|
548 /* This is here for backwards compatibility. Extensions that use the old GC |
|
549 * API will still compile but the objects will not be tracked by the GC. */ |
|
550 #define Py_TPFLAGS_GC 0 /* used to be (1L<<2) */ |
|
551 |
|
552 /* PySequenceMethods and PyNumberMethods contain in-place operators */ |
|
553 #define Py_TPFLAGS_HAVE_INPLACEOPS (1L<<3) |
|
554 |
|
555 /* PyNumberMethods do their own coercion */ |
|
556 #define Py_TPFLAGS_CHECKTYPES (1L<<4) |
|
557 |
|
558 /* tp_richcompare is defined */ |
|
559 #define Py_TPFLAGS_HAVE_RICHCOMPARE (1L<<5) |
|
560 |
|
561 /* Objects which are weakly referencable if their tp_weaklistoffset is >0 */ |
|
562 #define Py_TPFLAGS_HAVE_WEAKREFS (1L<<6) |
|
563 |
|
564 /* tp_iter is defined */ |
|
565 #define Py_TPFLAGS_HAVE_ITER (1L<<7) |
|
566 |
|
567 /* New members introduced by Python 2.2 exist */ |
|
568 #define Py_TPFLAGS_HAVE_CLASS (1L<<8) |
|
569 |
|
570 /* Set if the type object is dynamically allocated */ |
|
571 #define Py_TPFLAGS_HEAPTYPE (1L<<9) |
|
572 |
|
573 /* Set if the type allows subclassing */ |
|
574 #define Py_TPFLAGS_BASETYPE (1L<<10) |
|
575 |
|
576 /* Set if the type is 'ready' -- fully initialized */ |
|
577 #define Py_TPFLAGS_READY (1L<<12) |
|
578 |
|
579 /* Set while the type is being 'readied', to prevent recursive ready calls */ |
|
580 #define Py_TPFLAGS_READYING (1L<<13) |
|
581 |
|
582 /* Objects support garbage collection (see objimp.h) */ |
|
583 #define Py_TPFLAGS_HAVE_GC (1L<<14) |
|
584 |
|
585 /* These two bits are preserved for Stackless Python, next after this is 17 */ |
|
586 #ifdef STACKLESS |
|
587 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3L<<15) |
|
588 #else |
|
589 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0 |
|
590 #endif |
|
591 |
|
592 /* Objects support nb_index in PyNumberMethods */ |
|
593 #define Py_TPFLAGS_HAVE_INDEX (1L<<17) |
|
594 |
|
595 /* Objects support type attribute cache */ |
|
596 #define Py_TPFLAGS_HAVE_VERSION_TAG (1L<<18) |
|
597 #define Py_TPFLAGS_VALID_VERSION_TAG (1L<<19) |
|
598 |
|
599 /* Type is abstract and cannot be instantiated */ |
|
600 #define Py_TPFLAGS_IS_ABSTRACT (1L<<20) |
|
601 |
|
602 /* Has the new buffer protocol */ |
|
603 #define Py_TPFLAGS_HAVE_NEWBUFFER (1L<<21) |
|
604 |
|
605 /* These flags are used to determine if a type is a subclass. */ |
|
606 #define Py_TPFLAGS_INT_SUBCLASS (1L<<23) |
|
607 #define Py_TPFLAGS_LONG_SUBCLASS (1L<<24) |
|
608 #define Py_TPFLAGS_LIST_SUBCLASS (1L<<25) |
|
609 #define Py_TPFLAGS_TUPLE_SUBCLASS (1L<<26) |
|
610 #define Py_TPFLAGS_STRING_SUBCLASS (1L<<27) |
|
611 #define Py_TPFLAGS_UNICODE_SUBCLASS (1L<<28) |
|
612 #define Py_TPFLAGS_DICT_SUBCLASS (1L<<29) |
|
613 #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1L<<30) |
|
614 #define Py_TPFLAGS_TYPE_SUBCLASS (1L<<31) |
|
615 |
|
616 #define Py_TPFLAGS_DEFAULT_EXTERNAL ( \ |
|
617 Py_TPFLAGS_HAVE_GETCHARBUFFER | \ |
|
618 Py_TPFLAGS_HAVE_SEQUENCE_IN | \ |
|
619 Py_TPFLAGS_HAVE_INPLACEOPS | \ |
|
620 Py_TPFLAGS_HAVE_RICHCOMPARE | \ |
|
621 Py_TPFLAGS_HAVE_WEAKREFS | \ |
|
622 Py_TPFLAGS_HAVE_ITER | \ |
|
623 Py_TPFLAGS_HAVE_CLASS | \ |
|
624 Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \ |
|
625 Py_TPFLAGS_HAVE_INDEX | \ |
|
626 0) |
|
627 #define Py_TPFLAGS_DEFAULT_CORE (Py_TPFLAGS_DEFAULT_EXTERNAL | \ |
|
628 Py_TPFLAGS_HAVE_VERSION_TAG) |
|
629 |
|
630 #ifdef Py_BUILD_CORE |
|
631 #define Py_TPFLAGS_DEFAULT Py_TPFLAGS_DEFAULT_CORE |
|
632 #else |
|
633 #define Py_TPFLAGS_DEFAULT Py_TPFLAGS_DEFAULT_EXTERNAL |
|
634 #endif |
|
635 |
|
636 #define PyType_HasFeature(t,f) (((t)->tp_flags & (f)) != 0) |
|
637 #define PyType_FastSubclass(t,f) PyType_HasFeature(t,f) |
|
638 |
|
639 |
|
640 /* |
|
641 The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement |
|
642 reference counts. Py_DECREF calls the object's deallocator function when |
|
643 the refcount falls to 0; for |
|
644 objects that don't contain references to other objects or heap memory |
|
645 this can be the standard function free(). Both macros can be used |
|
646 wherever a void expression is allowed. The argument must not be a |
|
647 NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead. |
|
648 The macro _Py_NewReference(op) initialize reference counts to 1, and |
|
649 in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional |
|
650 bookkeeping appropriate to the special build. |
|
651 |
|
652 We assume that the reference count field can never overflow; this can |
|
653 be proven when the size of the field is the same as the pointer size, so |
|
654 we ignore the possibility. Provided a C int is at least 32 bits (which |
|
655 is implicitly assumed in many parts of this code), that's enough for |
|
656 about 2**31 references to an object. |
|
657 |
|
658 XXX The following became out of date in Python 2.2, but I'm not sure |
|
659 XXX what the full truth is now. Certainly, heap-allocated type objects |
|
660 XXX can and should be deallocated. |
|
661 Type objects should never be deallocated; the type pointer in an object |
|
662 is not considered to be a reference to the type object, to save |
|
663 complications in the deallocation function. (This is actually a |
|
664 decision that's up to the implementer of each new type so if you want, |
|
665 you can count such references to the type object.) |
|
666 |
|
667 *** WARNING*** The Py_DECREF macro must have a side-effect-free argument |
|
668 since it may evaluate its argument multiple times. (The alternative |
|
669 would be to mace it a proper function or assign it to a global temporary |
|
670 variable first, both of which are slower; and in a multi-threaded |
|
671 environment the global variable trick is not safe.) |
|
672 */ |
|
673 |
|
674 /* First define a pile of simple helper macros, one set per special |
|
675 * build symbol. These either expand to the obvious things, or to |
|
676 * nothing at all when the special mode isn't in effect. The main |
|
677 * macros can later be defined just once then, yet expand to different |
|
678 * things depending on which special build options are and aren't in effect. |
|
679 * Trust me <wink>: while painful, this is 20x easier to understand than, |
|
680 * e.g, defining _Py_NewReference five different times in a maze of nested |
|
681 * #ifdefs (we used to do that -- it was impenetrable). |
|
682 */ |
|
683 #ifdef Py_REF_DEBUG |
|
684 PyAPI_DATA(Py_ssize_t) _Py_RefTotal; |
|
685 PyAPI_FUNC(void) _Py_NegativeRefcount(const char *fname, |
|
686 int lineno, PyObject *op); |
|
687 PyAPI_FUNC(PyObject *) _PyDict_Dummy(void); |
|
688 PyAPI_FUNC(PyObject *) _PySet_Dummy(void); |
|
689 PyAPI_FUNC(Py_ssize_t) _Py_GetRefTotal(void); |
|
690 #define _Py_INC_REFTOTAL _Py_RefTotal++ |
|
691 #define _Py_DEC_REFTOTAL _Py_RefTotal-- |
|
692 #define _Py_REF_DEBUG_COMMA , |
|
693 #define _Py_CHECK_REFCNT(OP) \ |
|
694 { if (((PyObject*)OP)->ob_refcnt < 0) \ |
|
695 _Py_NegativeRefcount(__FILE__, __LINE__, \ |
|
696 (PyObject *)(OP)); \ |
|
697 } |
|
698 #else |
|
699 #define _Py_INC_REFTOTAL |
|
700 #define _Py_DEC_REFTOTAL |
|
701 #define _Py_REF_DEBUG_COMMA |
|
702 #define _Py_CHECK_REFCNT(OP) /* a semicolon */; |
|
703 #endif /* Py_REF_DEBUG */ |
|
704 |
|
705 #ifdef COUNT_ALLOCS |
|
706 PyAPI_FUNC(void) inc_count(PyTypeObject *); |
|
707 PyAPI_FUNC(void) dec_count(PyTypeObject *); |
|
708 #define _Py_INC_TPALLOCS(OP) inc_count(Py_TYPE(OP)) |
|
709 #define _Py_INC_TPFREES(OP) dec_count(Py_TYPE(OP)) |
|
710 #define _Py_DEC_TPFREES(OP) Py_TYPE(OP)->tp_frees-- |
|
711 #define _Py_COUNT_ALLOCS_COMMA , |
|
712 #else |
|
713 #define _Py_INC_TPALLOCS(OP) |
|
714 #define _Py_INC_TPFREES(OP) |
|
715 #define _Py_DEC_TPFREES(OP) |
|
716 #define _Py_COUNT_ALLOCS_COMMA |
|
717 #endif /* COUNT_ALLOCS */ |
|
718 |
|
719 #ifdef Py_TRACE_REFS |
|
720 /* Py_TRACE_REFS is such major surgery that we call external routines. */ |
|
721 PyAPI_FUNC(void) _Py_NewReference(PyObject *); |
|
722 PyAPI_FUNC(void) _Py_ForgetReference(PyObject *); |
|
723 PyAPI_FUNC(void) _Py_Dealloc(PyObject *); |
|
724 PyAPI_FUNC(void) _Py_PrintReferences(FILE *); |
|
725 PyAPI_FUNC(void) _Py_PrintReferenceAddresses(FILE *); |
|
726 PyAPI_FUNC(void) _Py_AddToAllObjects(PyObject *, int force); |
|
727 |
|
728 #else |
|
729 /* Without Py_TRACE_REFS, there's little enough to do that we expand code |
|
730 * inline. |
|
731 */ |
|
732 #define _Py_NewReference(op) ( \ |
|
733 _Py_INC_TPALLOCS(op) _Py_COUNT_ALLOCS_COMMA \ |
|
734 _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \ |
|
735 Py_REFCNT(op) = 1) |
|
736 |
|
737 #define _Py_ForgetReference(op) _Py_INC_TPFREES(op) |
|
738 |
|
739 #define _Py_Dealloc(op) ( \ |
|
740 _Py_INC_TPFREES(op) _Py_COUNT_ALLOCS_COMMA \ |
|
741 (*Py_TYPE(op)->tp_dealloc)((PyObject *)(op))) |
|
742 #endif /* !Py_TRACE_REFS */ |
|
743 |
|
744 #define Py_INCREF(op) ( \ |
|
745 _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \ |
|
746 ((PyObject*)(op))->ob_refcnt++) |
|
747 |
|
748 #define Py_DECREF(op) \ |
|
749 if (_Py_DEC_REFTOTAL _Py_REF_DEBUG_COMMA \ |
|
750 --((PyObject*)(op))->ob_refcnt != 0) \ |
|
751 _Py_CHECK_REFCNT(op) \ |
|
752 else \ |
|
753 _Py_Dealloc((PyObject *)(op)) |
|
754 |
|
755 /* Safely decref `op` and set `op` to NULL, especially useful in tp_clear |
|
756 * and tp_dealloc implementatons. |
|
757 * |
|
758 * Note that "the obvious" code can be deadly: |
|
759 * |
|
760 * Py_XDECREF(op); |
|
761 * op = NULL; |
|
762 * |
|
763 * Typically, `op` is something like self->containee, and `self` is done |
|
764 * using its `containee` member. In the code sequence above, suppose |
|
765 * `containee` is non-NULL with a refcount of 1. Its refcount falls to |
|
766 * 0 on the first line, which can trigger an arbitrary amount of code, |
|
767 * possibly including finalizers (like __del__ methods or weakref callbacks) |
|
768 * coded in Python, which in turn can release the GIL and allow other threads |
|
769 * to run, etc. Such code may even invoke methods of `self` again, or cause |
|
770 * cyclic gc to trigger, but-- oops! --self->containee still points to the |
|
771 * object being torn down, and it may be in an insane state while being torn |
|
772 * down. This has in fact been a rich historic source of miserable (rare & |
|
773 * hard-to-diagnose) segfaulting (and other) bugs. |
|
774 * |
|
775 * The safe way is: |
|
776 * |
|
777 * Py_CLEAR(op); |
|
778 * |
|
779 * That arranges to set `op` to NULL _before_ decref'ing, so that any code |
|
780 * triggered as a side-effect of `op` getting torn down no longer believes |
|
781 * `op` points to a valid object. |
|
782 * |
|
783 * There are cases where it's safe to use the naive code, but they're brittle. |
|
784 * For example, if `op` points to a Python integer, you know that destroying |
|
785 * one of those can't cause problems -- but in part that relies on that |
|
786 * Python integers aren't currently weakly referencable. Best practice is |
|
787 * to use Py_CLEAR() even if you can't think of a reason for why you need to. |
|
788 */ |
|
789 #define Py_CLEAR(op) \ |
|
790 do { \ |
|
791 if (op) { \ |
|
792 PyObject *_py_tmp = (PyObject *)(op); \ |
|
793 (op) = NULL; \ |
|
794 Py_DECREF(_py_tmp); \ |
|
795 } \ |
|
796 } while (0) |
|
797 |
|
798 /* Macros to use in case the object pointer may be NULL: */ |
|
799 #define Py_XINCREF(op) if ((op) == NULL) ; else Py_INCREF(op) |
|
800 #define Py_XDECREF(op) if ((op) == NULL) ; else Py_DECREF(op) |
|
801 |
|
802 /* |
|
803 These are provided as conveniences to Python runtime embedders, so that |
|
804 they can have object code that is not dependent on Python compilation flags. |
|
805 */ |
|
806 PyAPI_FUNC(void) Py_IncRef(PyObject *); |
|
807 PyAPI_FUNC(void) Py_DecRef(PyObject *); |
|
808 |
|
809 /* |
|
810 _Py_NoneStruct is an object of undefined type which can be used in contexts |
|
811 where NULL (nil) is not suitable (since NULL often means 'error'). |
|
812 |
|
813 Don't forget to apply Py_INCREF() when returning this value!!! |
|
814 */ |
|
815 PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */ |
|
816 #define Py_None (&_Py_NoneStruct) |
|
817 |
|
818 /* Macro for returning Py_None from a function */ |
|
819 #define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None |
|
820 |
|
821 /* |
|
822 Py_NotImplemented is a singleton used to signal that an operation is |
|
823 not implemented for a given type combination. |
|
824 */ |
|
825 PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */ |
|
826 #define Py_NotImplemented (&_Py_NotImplementedStruct) |
|
827 |
|
828 /* Rich comparison opcodes */ |
|
829 #define Py_LT 0 |
|
830 #define Py_LE 1 |
|
831 #define Py_EQ 2 |
|
832 #define Py_NE 3 |
|
833 #define Py_GT 4 |
|
834 #define Py_GE 5 |
|
835 |
|
836 /* Maps Py_LT to Py_GT, ..., Py_GE to Py_LE. |
|
837 * Defined in object.c. |
|
838 */ |
|
839 PyAPI_DATA(int) _Py_SwappedOp[]; |
|
840 |
|
841 /* |
|
842 Define staticforward and statichere for source compatibility with old |
|
843 C extensions. |
|
844 |
|
845 The staticforward define was needed to support certain broken C |
|
846 compilers (notably SCO ODT 3.0, perhaps early AIX as well) botched the |
|
847 static keyword when it was used with a forward declaration of a static |
|
848 initialized structure. Standard C allows the forward declaration with |
|
849 static, and we've decided to stop catering to broken C compilers. |
|
850 (In fact, we expect that the compilers are all fixed eight years later.) |
|
851 */ |
|
852 |
|
853 #define staticforward static |
|
854 #define statichere static |
|
855 |
|
856 |
|
857 /* |
|
858 More conventions |
|
859 ================ |
|
860 |
|
861 Argument Checking |
|
862 ----------------- |
|
863 |
|
864 Functions that take objects as arguments normally don't check for nil |
|
865 arguments, but they do check the type of the argument, and return an |
|
866 error if the function doesn't apply to the type. |
|
867 |
|
868 Failure Modes |
|
869 ------------- |
|
870 |
|
871 Functions may fail for a variety of reasons, including running out of |
|
872 memory. This is communicated to the caller in two ways: an error string |
|
873 is set (see errors.h), and the function result differs: functions that |
|
874 normally return a pointer return NULL for failure, functions returning |
|
875 an integer return -1 (which could be a legal return value too!), and |
|
876 other functions return 0 for success and -1 for failure. |
|
877 Callers should always check for errors before using the result. If |
|
878 an error was set, the caller must either explicitly clear it, or pass |
|
879 the error on to its caller. |
|
880 |
|
881 Reference Counts |
|
882 ---------------- |
|
883 |
|
884 It takes a while to get used to the proper usage of reference counts. |
|
885 |
|
886 Functions that create an object set the reference count to 1; such new |
|
887 objects must be stored somewhere or destroyed again with Py_DECREF(). |
|
888 Some functions that 'store' objects, such as PyTuple_SetItem() and |
|
889 PyList_SetItem(), |
|
890 don't increment the reference count of the object, since the most |
|
891 frequent use is to store a fresh object. Functions that 'retrieve' |
|
892 objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also |
|
893 don't increment |
|
894 the reference count, since most frequently the object is only looked at |
|
895 quickly. Thus, to retrieve an object and store it again, the caller |
|
896 must call Py_INCREF() explicitly. |
|
897 |
|
898 NOTE: functions that 'consume' a reference count, like |
|
899 PyList_SetItem(), consume the reference even if the object wasn't |
|
900 successfully stored, to simplify error handling. |
|
901 |
|
902 It seems attractive to make other functions that take an object as |
|
903 argument consume a reference count; however, this may quickly get |
|
904 confusing (even the current practice is already confusing). Consider |
|
905 it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at |
|
906 times. |
|
907 */ |
|
908 |
|
909 |
|
910 /* Trashcan mechanism, thanks to Christian Tismer. |
|
911 |
|
912 When deallocating a container object, it's possible to trigger an unbounded |
|
913 chain of deallocations, as each Py_DECREF in turn drops the refcount on "the |
|
914 next" object in the chain to 0. This can easily lead to stack faults, and |
|
915 especially in threads (which typically have less stack space to work with). |
|
916 |
|
917 A container object that participates in cyclic gc can avoid this by |
|
918 bracketing the body of its tp_dealloc function with a pair of macros: |
|
919 |
|
920 static void |
|
921 mytype_dealloc(mytype *p) |
|
922 { |
|
923 ... declarations go here ... |
|
924 |
|
925 PyObject_GC_UnTrack(p); // must untrack first |
|
926 Py_TRASHCAN_SAFE_BEGIN(p) |
|
927 ... The body of the deallocator goes here, including all calls ... |
|
928 ... to Py_DECREF on contained objects. ... |
|
929 Py_TRASHCAN_SAFE_END(p) |
|
930 } |
|
931 |
|
932 CAUTION: Never return from the middle of the body! If the body needs to |
|
933 "get out early", put a label immediately before the Py_TRASHCAN_SAFE_END |
|
934 call, and goto it. Else the call-depth counter (see below) will stay |
|
935 above 0 forever, and the trashcan will never get emptied. |
|
936 |
|
937 How it works: The BEGIN macro increments a call-depth counter. So long |
|
938 as this counter is small, the body of the deallocator is run directly without |
|
939 further ado. But if the counter gets large, it instead adds p to a list of |
|
940 objects to be deallocated later, skips the body of the deallocator, and |
|
941 resumes execution after the END macro. The tp_dealloc routine then returns |
|
942 without deallocating anything (and so unbounded call-stack depth is avoided). |
|
943 |
|
944 When the call stack finishes unwinding again, code generated by the END macro |
|
945 notices this, and calls another routine to deallocate all the objects that |
|
946 may have been added to the list of deferred deallocations. In effect, a |
|
947 chain of N deallocations is broken into N / PyTrash_UNWIND_LEVEL pieces, |
|
948 with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL. |
|
949 */ |
|
950 |
|
951 PyAPI_FUNC(void) _PyTrash_deposit_object(PyObject*); |
|
952 PyAPI_FUNC(void) _PyTrash_destroy_chain(void); |
|
953 PyAPI_DATA(int) _PyTrash_delete_nesting; |
|
954 PyAPI_DATA(PyObject *) _PyTrash_delete_later; |
|
955 |
|
956 #define PyTrash_UNWIND_LEVEL 50 |
|
957 |
|
958 #define Py_TRASHCAN_SAFE_BEGIN(op) \ |
|
959 if (_PyTrash_delete_nesting < PyTrash_UNWIND_LEVEL) { \ |
|
960 ++_PyTrash_delete_nesting; |
|
961 /* The body of the deallocator is here. */ |
|
962 #define Py_TRASHCAN_SAFE_END(op) \ |
|
963 --_PyTrash_delete_nesting; \ |
|
964 if (_PyTrash_delete_later && _PyTrash_delete_nesting <= 0) \ |
|
965 _PyTrash_destroy_chain(); \ |
|
966 } \ |
|
967 else \ |
|
968 _PyTrash_deposit_object((PyObject*)op); |
|
969 |
|
970 #ifdef __cplusplus |
|
971 } |
|
972 #endif |
|
973 #endif /* !Py_OBJECT_H */ |