Commit | Line | Data |
---|---|---|
86530b38 AT |
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 | int ob_refcnt; \ | |
81 | struct _typeobject *ob_type; | |
82 | ||
83 | #define PyObject_HEAD_INIT(type) \ | |
84 | _PyObject_EXTRA_INIT \ | |
85 | 1, type, | |
86 | ||
87 | /* PyObject_VAR_HEAD defines the initial segment of all variable-size | |
88 | * container objects. These end with a declaration of an array with 1 | |
89 | * element, but enough space is malloc'ed so that the array actually | |
90 | * has room for ob_size elements. Note that ob_size is an element count, | |
91 | * not necessarily a byte count. | |
92 | */ | |
93 | #define PyObject_VAR_HEAD \ | |
94 | PyObject_HEAD \ | |
95 | int ob_size; /* Number of items in variable part */ | |
96 | ||
97 | /* Nothing is actually declared to be a PyObject, but every pointer to | |
98 | * a Python object can be cast to a PyObject*. This is inheritance built | |
99 | * by hand. Similarly every pointer to a variable-size Python object can, | |
100 | * in addition, be cast to PyVarObject*. | |
101 | */ | |
102 | typedef struct _object { | |
103 | PyObject_HEAD | |
104 | } PyObject; | |
105 | ||
106 | typedef struct { | |
107 | PyObject_VAR_HEAD | |
108 | } PyVarObject; | |
109 | ||
110 | ||
111 | /* | |
112 | Type objects contain a string containing the type name (to help somewhat | |
113 | in debugging), the allocation parameters (see PyObject_New() and | |
114 | PyObject_NewVar()), | |
115 | and methods for accessing objects of the type. Methods are optional, a | |
116 | nil pointer meaning that particular kind of access is not available for | |
117 | this type. The Py_DECREF() macro uses the tp_dealloc method without | |
118 | checking for a nil pointer; it should always be implemented except if | |
119 | the implementation can guarantee that the reference count will never | |
120 | reach zero (e.g., for statically allocated type objects). | |
121 | ||
122 | NB: the methods for certain type groups are now contained in separate | |
123 | method blocks. | |
124 | */ | |
125 | ||
126 | typedef PyObject * (*unaryfunc)(PyObject *); | |
127 | typedef PyObject * (*binaryfunc)(PyObject *, PyObject *); | |
128 | typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *); | |
129 | typedef int (*inquiry)(PyObject *); | |
130 | typedef int (*coercion)(PyObject **, PyObject **); | |
131 | typedef PyObject *(*intargfunc)(PyObject *, int); | |
132 | typedef PyObject *(*intintargfunc)(PyObject *, int, int); | |
133 | typedef int(*intobjargproc)(PyObject *, int, PyObject *); | |
134 | typedef int(*intintobjargproc)(PyObject *, int, int, PyObject *); | |
135 | typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *); | |
136 | typedef int (*getreadbufferproc)(PyObject *, int, void **); | |
137 | typedef int (*getwritebufferproc)(PyObject *, int, void **); | |
138 | typedef int (*getsegcountproc)(PyObject *, int *); | |
139 | typedef int (*getcharbufferproc)(PyObject *, int, const char **); | |
140 | typedef int (*objobjproc)(PyObject *, PyObject *); | |
141 | typedef int (*visitproc)(PyObject *, void *); | |
142 | typedef int (*traverseproc)(PyObject *, visitproc, void *); | |
143 | ||
144 | typedef struct { | |
145 | /* For numbers without flag bit Py_TPFLAGS_CHECKTYPES set, all | |
146 | arguments are guaranteed to be of the object's type (modulo | |
147 | coercion hacks -- i.e. if the type's coercion function | |
148 | returns other types, then these are allowed as well). Numbers that | |
149 | have the Py_TPFLAGS_CHECKTYPES flag bit set should check *both* | |
150 | arguments for proper type and implement the necessary conversions | |
151 | in the slot functions themselves. */ | |
152 | ||
153 | binaryfunc nb_add; | |
154 | binaryfunc nb_subtract; | |
155 | binaryfunc nb_multiply; | |
156 | binaryfunc nb_divide; | |
157 | binaryfunc nb_remainder; | |
158 | binaryfunc nb_divmod; | |
159 | ternaryfunc nb_power; | |
160 | unaryfunc nb_negative; | |
161 | unaryfunc nb_positive; | |
162 | unaryfunc nb_absolute; | |
163 | inquiry nb_nonzero; | |
164 | unaryfunc nb_invert; | |
165 | binaryfunc nb_lshift; | |
166 | binaryfunc nb_rshift; | |
167 | binaryfunc nb_and; | |
168 | binaryfunc nb_xor; | |
169 | binaryfunc nb_or; | |
170 | coercion nb_coerce; | |
171 | unaryfunc nb_int; | |
172 | unaryfunc nb_long; | |
173 | unaryfunc nb_float; | |
174 | unaryfunc nb_oct; | |
175 | unaryfunc nb_hex; | |
176 | /* Added in release 2.0 */ | |
177 | binaryfunc nb_inplace_add; | |
178 | binaryfunc nb_inplace_subtract; | |
179 | binaryfunc nb_inplace_multiply; | |
180 | binaryfunc nb_inplace_divide; | |
181 | binaryfunc nb_inplace_remainder; | |
182 | ternaryfunc nb_inplace_power; | |
183 | binaryfunc nb_inplace_lshift; | |
184 | binaryfunc nb_inplace_rshift; | |
185 | binaryfunc nb_inplace_and; | |
186 | binaryfunc nb_inplace_xor; | |
187 | binaryfunc nb_inplace_or; | |
188 | ||
189 | /* Added in release 2.2 */ | |
190 | /* The following require the Py_TPFLAGS_HAVE_CLASS flag */ | |
191 | binaryfunc nb_floor_divide; | |
192 | binaryfunc nb_true_divide; | |
193 | binaryfunc nb_inplace_floor_divide; | |
194 | binaryfunc nb_inplace_true_divide; | |
195 | } PyNumberMethods; | |
196 | ||
197 | typedef struct { | |
198 | inquiry sq_length; | |
199 | binaryfunc sq_concat; | |
200 | intargfunc sq_repeat; | |
201 | intargfunc sq_item; | |
202 | intintargfunc sq_slice; | |
203 | intobjargproc sq_ass_item; | |
204 | intintobjargproc sq_ass_slice; | |
205 | objobjproc sq_contains; | |
206 | /* Added in release 2.0 */ | |
207 | binaryfunc sq_inplace_concat; | |
208 | intargfunc sq_inplace_repeat; | |
209 | } PySequenceMethods; | |
210 | ||
211 | typedef struct { | |
212 | inquiry mp_length; | |
213 | binaryfunc mp_subscript; | |
214 | objobjargproc mp_ass_subscript; | |
215 | } PyMappingMethods; | |
216 | ||
217 | typedef struct { | |
218 | getreadbufferproc bf_getreadbuffer; | |
219 | getwritebufferproc bf_getwritebuffer; | |
220 | getsegcountproc bf_getsegcount; | |
221 | getcharbufferproc bf_getcharbuffer; | |
222 | } PyBufferProcs; | |
223 | ||
224 | ||
225 | typedef void (*freefunc)(void *); | |
226 | typedef void (*destructor)(PyObject *); | |
227 | typedef int (*printfunc)(PyObject *, FILE *, int); | |
228 | typedef PyObject *(*getattrfunc)(PyObject *, char *); | |
229 | typedef PyObject *(*getattrofunc)(PyObject *, PyObject *); | |
230 | typedef int (*setattrfunc)(PyObject *, char *, PyObject *); | |
231 | typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *); | |
232 | typedef int (*cmpfunc)(PyObject *, PyObject *); | |
233 | typedef PyObject *(*reprfunc)(PyObject *); | |
234 | typedef long (*hashfunc)(PyObject *); | |
235 | typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int); | |
236 | typedef PyObject *(*getiterfunc) (PyObject *); | |
237 | typedef PyObject *(*iternextfunc) (PyObject *); | |
238 | typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *); | |
239 | typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *); | |
240 | typedef int (*initproc)(PyObject *, PyObject *, PyObject *); | |
241 | typedef PyObject *(*newfunc)(struct _typeobject *, PyObject *, PyObject *); | |
242 | typedef PyObject *(*allocfunc)(struct _typeobject *, int); | |
243 | ||
244 | typedef struct _typeobject { | |
245 | PyObject_VAR_HEAD | |
246 | char *tp_name; /* For printing, in format "<module>.<name>" */ | |
247 | int tp_basicsize, tp_itemsize; /* For allocation */ | |
248 | ||
249 | /* Methods to implement standard operations */ | |
250 | ||
251 | destructor tp_dealloc; | |
252 | printfunc tp_print; | |
253 | getattrfunc tp_getattr; | |
254 | setattrfunc tp_setattr; | |
255 | cmpfunc tp_compare; | |
256 | reprfunc tp_repr; | |
257 | ||
258 | /* Method suites for standard classes */ | |
259 | ||
260 | PyNumberMethods *tp_as_number; | |
261 | PySequenceMethods *tp_as_sequence; | |
262 | PyMappingMethods *tp_as_mapping; | |
263 | ||
264 | /* More standard operations (here for binary compatibility) */ | |
265 | ||
266 | hashfunc tp_hash; | |
267 | ternaryfunc tp_call; | |
268 | reprfunc tp_str; | |
269 | getattrofunc tp_getattro; | |
270 | setattrofunc tp_setattro; | |
271 | ||
272 | /* Functions to access object as input/output buffer */ | |
273 | PyBufferProcs *tp_as_buffer; | |
274 | ||
275 | /* Flags to define presence of optional/expanded features */ | |
276 | long tp_flags; | |
277 | ||
278 | char *tp_doc; /* Documentation string */ | |
279 | ||
280 | /* Assigned meaning in release 2.0 */ | |
281 | /* call function for all accessible objects */ | |
282 | traverseproc tp_traverse; | |
283 | ||
284 | /* delete references to contained objects */ | |
285 | inquiry tp_clear; | |
286 | ||
287 | /* Assigned meaning in release 2.1 */ | |
288 | /* rich comparisons */ | |
289 | richcmpfunc tp_richcompare; | |
290 | ||
291 | /* weak reference enabler */ | |
292 | long tp_weaklistoffset; | |
293 | ||
294 | /* Added in release 2.2 */ | |
295 | /* Iterators */ | |
296 | getiterfunc tp_iter; | |
297 | iternextfunc tp_iternext; | |
298 | ||
299 | /* Attribute descriptor and subclassing stuff */ | |
300 | struct PyMethodDef *tp_methods; | |
301 | struct PyMemberDef *tp_members; | |
302 | struct PyGetSetDef *tp_getset; | |
303 | struct _typeobject *tp_base; | |
304 | PyObject *tp_dict; | |
305 | descrgetfunc tp_descr_get; | |
306 | descrsetfunc tp_descr_set; | |
307 | long tp_dictoffset; | |
308 | initproc tp_init; | |
309 | allocfunc tp_alloc; | |
310 | newfunc tp_new; | |
311 | freefunc tp_free; /* Low-level free-memory routine */ | |
312 | inquiry tp_is_gc; /* For PyObject_IS_GC */ | |
313 | PyObject *tp_bases; | |
314 | PyObject *tp_mro; /* method resolution order */ | |
315 | PyObject *tp_cache; | |
316 | PyObject *tp_subclasses; | |
317 | PyObject *tp_weaklist; | |
318 | destructor tp_del; | |
319 | ||
320 | #ifdef COUNT_ALLOCS | |
321 | /* these must be last and never explicitly initialized */ | |
322 | int tp_allocs; | |
323 | int tp_frees; | |
324 | int tp_maxalloc; | |
325 | struct _typeobject *tp_next; | |
326 | #endif | |
327 | } PyTypeObject; | |
328 | ||
329 | ||
330 | /* The *real* layout of a type object when allocated on the heap */ | |
331 | typedef struct _heaptypeobject { | |
332 | /* Note: there's a dependency on the order of these members | |
333 | in slotptr() in typeobject.c . */ | |
334 | PyTypeObject type; | |
335 | PyNumberMethods as_number; | |
336 | PyMappingMethods as_mapping; | |
337 | PySequenceMethods as_sequence; /* as_sequence comes after as_mapping, | |
338 | so that the mapping wins when both | |
339 | the mapping and the sequence define | |
340 | a given operator (e.g. __getitem__). | |
341 | see add_operators() in typeobject.c . */ | |
342 | PyBufferProcs as_buffer; | |
343 | PyObject *name, *slots; | |
344 | /* here are optional user slots, followed by the members. */ | |
345 | } PyHeapTypeObject; | |
346 | ||
347 | /* access macro to the members which are floating "behind" the object */ | |
348 | #define PyHeapType_GET_MEMBERS(etype) \ | |
349 | ((PyMemberDef *)(((char *)etype) + (etype)->type.ob_type->tp_basicsize)) | |
350 | ||
351 | ||
352 | /* Generic type check */ | |
353 | PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *); | |
354 | #define PyObject_TypeCheck(ob, tp) \ | |
355 | ((ob)->ob_type == (tp) || PyType_IsSubtype((ob)->ob_type, (tp))) | |
356 | ||
357 | PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */ | |
358 | PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */ | |
359 | PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */ | |
360 | ||
361 | #define PyType_Check(op) PyObject_TypeCheck(op, &PyType_Type) | |
362 | #define PyType_CheckExact(op) ((op)->ob_type == &PyType_Type) | |
363 | ||
364 | PyAPI_FUNC(int) PyType_Ready(PyTypeObject *); | |
365 | PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, int); | |
366 | PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *, | |
367 | PyObject *, PyObject *); | |
368 | PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *); | |
369 | ||
370 | /* Generic operations on objects */ | |
371 | PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int); | |
372 | PyAPI_FUNC(void) _PyObject_Dump(PyObject *); | |
373 | PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *); | |
374 | PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *); | |
375 | #ifdef Py_USING_UNICODE | |
376 | PyAPI_FUNC(PyObject *) PyObject_Unicode(PyObject *); | |
377 | #endif | |
378 | PyAPI_FUNC(int) PyObject_Compare(PyObject *, PyObject *); | |
379 | PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int); | |
380 | PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int); | |
381 | PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, char *); | |
382 | PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, char *, PyObject *); | |
383 | PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, char *); | |
384 | PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *); | |
385 | PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *); | |
386 | PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *); | |
387 | PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *); | |
388 | PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *); | |
389 | PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *); | |
390 | PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, | |
391 | PyObject *, PyObject *); | |
392 | PyAPI_FUNC(long) PyObject_Hash(PyObject *); | |
393 | PyAPI_FUNC(int) PyObject_IsTrue(PyObject *); | |
394 | PyAPI_FUNC(int) PyObject_Not(PyObject *); | |
395 | PyAPI_FUNC(int) PyCallable_Check(PyObject *); | |
396 | PyAPI_FUNC(int) PyNumber_Coerce(PyObject **, PyObject **); | |
397 | PyAPI_FUNC(int) PyNumber_CoerceEx(PyObject **, PyObject **); | |
398 | ||
399 | PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *); | |
400 | ||
401 | /* A slot function whose address we need to compare */ | |
402 | extern int _PyObject_SlotCompare(PyObject *, PyObject *); | |
403 | ||
404 | ||
405 | /* PyObject_Dir(obj) acts like Python __builtin__.dir(obj), returning a | |
406 | list of strings. PyObject_Dir(NULL) is like __builtin__.dir(), | |
407 | returning the names of the current locals. In this case, if there are | |
408 | no current locals, NULL is returned, and PyErr_Occurred() is false. | |
409 | */ | |
410 | PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *); | |
411 | ||
412 | ||
413 | /* Helpers for printing recursive container types */ | |
414 | PyAPI_FUNC(int) Py_ReprEnter(PyObject *); | |
415 | PyAPI_FUNC(void) Py_ReprLeave(PyObject *); | |
416 | ||
417 | /* Helpers for hash functions */ | |
418 | PyAPI_FUNC(long) _Py_HashDouble(double); | |
419 | PyAPI_FUNC(long) _Py_HashPointer(void*); | |
420 | ||
421 | /* Helper for passing objects to printf and the like */ | |
422 | #define PyObject_REPR(obj) PyString_AS_STRING(PyObject_Repr(obj)) | |
423 | ||
424 | /* Flag bits for printing: */ | |
425 | #define Py_PRINT_RAW 1 /* No string quotes etc. */ | |
426 | ||
427 | /* | |
428 | `Type flags (tp_flags) | |
429 | ||
430 | These flags are used to extend the type structure in a backwards-compatible | |
431 | fashion. Extensions can use the flags to indicate (and test) when a given | |
432 | type structure contains a new feature. The Python core will use these when | |
433 | introducing new functionality between major revisions (to avoid mid-version | |
434 | changes in the PYTHON_API_VERSION). | |
435 | ||
436 | Arbitration of the flag bit positions will need to be coordinated among | |
437 | all extension writers who publically release their extensions (this will | |
438 | be fewer than you might expect!).. | |
439 | ||
440 | Python 1.5.2 introduced the bf_getcharbuffer slot into PyBufferProcs. | |
441 | ||
442 | Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value. | |
443 | ||
444 | Code can use PyType_HasFeature(type_ob, flag_value) to test whether the | |
445 | given type object has a specified feature. | |
446 | */ | |
447 | ||
448 | /* PyBufferProcs contains bf_getcharbuffer */ | |
449 | #define Py_TPFLAGS_HAVE_GETCHARBUFFER (1L<<0) | |
450 | ||
451 | /* PySequenceMethods contains sq_contains */ | |
452 | #define Py_TPFLAGS_HAVE_SEQUENCE_IN (1L<<1) | |
453 | ||
454 | /* This is here for backwards compatibility. Extensions that use the old GC | |
455 | * API will still compile but the objects will not be tracked by the GC. */ | |
456 | #define Py_TPFLAGS_GC 0 /* used to be (1L<<2) */ | |
457 | ||
458 | /* PySequenceMethods and PyNumberMethods contain in-place operators */ | |
459 | #define Py_TPFLAGS_HAVE_INPLACEOPS (1L<<3) | |
460 | ||
461 | /* PyNumberMethods do their own coercion */ | |
462 | #define Py_TPFLAGS_CHECKTYPES (1L<<4) | |
463 | ||
464 | /* tp_richcompare is defined */ | |
465 | #define Py_TPFLAGS_HAVE_RICHCOMPARE (1L<<5) | |
466 | ||
467 | /* Objects which are weakly referencable if their tp_weaklistoffset is >0 */ | |
468 | #define Py_TPFLAGS_HAVE_WEAKREFS (1L<<6) | |
469 | ||
470 | /* tp_iter is defined */ | |
471 | #define Py_TPFLAGS_HAVE_ITER (1L<<7) | |
472 | ||
473 | /* New members introduced by Python 2.2 exist */ | |
474 | #define Py_TPFLAGS_HAVE_CLASS (1L<<8) | |
475 | ||
476 | /* Set if the type object is dynamically allocated */ | |
477 | #define Py_TPFLAGS_HEAPTYPE (1L<<9) | |
478 | ||
479 | /* Set if the type allows subclassing */ | |
480 | #define Py_TPFLAGS_BASETYPE (1L<<10) | |
481 | ||
482 | /* Set if the type is 'ready' -- fully initialized */ | |
483 | #define Py_TPFLAGS_READY (1L<<12) | |
484 | ||
485 | /* Set while the type is being 'readied', to prevent recursive ready calls */ | |
486 | #define Py_TPFLAGS_READYING (1L<<13) | |
487 | ||
488 | /* Objects support garbage collection (see objimp.h) */ | |
489 | #define Py_TPFLAGS_HAVE_GC (1L<<14) | |
490 | ||
491 | /* These two bits are preserved for Stackless Python, next after this is 16 */ | |
492 | #ifdef STACKLESS | |
493 | #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3L<<15) | |
494 | #else | |
495 | #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0 | |
496 | #endif | |
497 | ||
498 | #define Py_TPFLAGS_DEFAULT ( \ | |
499 | Py_TPFLAGS_HAVE_GETCHARBUFFER | \ | |
500 | Py_TPFLAGS_HAVE_SEQUENCE_IN | \ | |
501 | Py_TPFLAGS_HAVE_INPLACEOPS | \ | |
502 | Py_TPFLAGS_HAVE_RICHCOMPARE | \ | |
503 | Py_TPFLAGS_HAVE_WEAKREFS | \ | |
504 | Py_TPFLAGS_HAVE_ITER | \ | |
505 | Py_TPFLAGS_HAVE_CLASS | \ | |
506 | Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \ | |
507 | 0) | |
508 | ||
509 | #define PyType_HasFeature(t,f) (((t)->tp_flags & (f)) != 0) | |
510 | ||
511 | ||
512 | /* | |
513 | The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement | |
514 | reference counts. Py_DECREF calls the object's deallocator function when | |
515 | the refcount falls to 0; for | |
516 | objects that don't contain references to other objects or heap memory | |
517 | this can be the standard function free(). Both macros can be used | |
518 | wherever a void expression is allowed. The argument must not be a | |
519 | NIL pointer. If it may be NIL, use Py_XINCREF/Py_XDECREF instead. | |
520 | The macro _Py_NewReference(op) initialize reference counts to 1, and | |
521 | in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional | |
522 | bookkeeping appropriate to the special build. | |
523 | ||
524 | We assume that the reference count field can never overflow; this can | |
525 | be proven when the size of the field is the same as the pointer size, so | |
526 | we ignore the possibility. Provided a C int is at least 32 bits (which | |
527 | is implicitly assumed in many parts of this code), that's enough for | |
528 | about 2**31 references to an object. | |
529 | ||
530 | XXX The following became out of date in Python 2.2, but I'm not sure | |
531 | XXX what the full truth is now. Certainly, heap-allocated type objects | |
532 | XXX can and should be deallocated. | |
533 | Type objects should never be deallocated; the type pointer in an object | |
534 | is not considered to be a reference to the type object, to save | |
535 | complications in the deallocation function. (This is actually a | |
536 | decision that's up to the implementer of each new type so if you want, | |
537 | you can count such references to the type object.) | |
538 | ||
539 | *** WARNING*** The Py_DECREF macro must have a side-effect-free argument | |
540 | since it may evaluate its argument multiple times. (The alternative | |
541 | would be to mace it a proper function or assign it to a global temporary | |
542 | variable first, both of which are slower; and in a multi-threaded | |
543 | environment the global variable trick is not safe.) | |
544 | */ | |
545 | ||
546 | /* First define a pile of simple helper macros, one set per special | |
547 | * build symbol. These either expand to the obvious things, or to | |
548 | * nothing at all when the special mode isn't in effect. The main | |
549 | * macros can later be defined just once then, yet expand to different | |
550 | * things depending on which special build options are and aren't in effect. | |
551 | * Trust me <wink>: while painful, this is 20x easier to understand than, | |
552 | * e.g, defining _Py_NewReference five different times in a maze of nested | |
553 | * #ifdefs (we used to do that -- it was impenetrable). | |
554 | */ | |
555 | #ifdef Py_REF_DEBUG | |
556 | PyAPI_DATA(long) _Py_RefTotal; | |
557 | PyAPI_FUNC(void) _Py_NegativeRefcount(const char *fname, | |
558 | int lineno, PyObject *op); | |
559 | #define _Py_INC_REFTOTAL _Py_RefTotal++ | |
560 | #define _Py_DEC_REFTOTAL _Py_RefTotal-- | |
561 | #define _Py_REF_DEBUG_COMMA , | |
562 | #define _Py_CHECK_REFCNT(OP) \ | |
563 | { if ((OP)->ob_refcnt < 0) \ | |
564 | _Py_NegativeRefcount(__FILE__, __LINE__, \ | |
565 | (PyObject *)(OP)); \ | |
566 | } | |
567 | #else | |
568 | #define _Py_INC_REFTOTAL | |
569 | #define _Py_DEC_REFTOTAL | |
570 | #define _Py_REF_DEBUG_COMMA | |
571 | #define _Py_CHECK_REFCNT(OP) /* a semicolon */; | |
572 | #endif /* Py_REF_DEBUG */ | |
573 | ||
574 | #ifdef COUNT_ALLOCS | |
575 | PyAPI_FUNC(void) inc_count(PyTypeObject *); | |
576 | #define _Py_INC_TPALLOCS(OP) inc_count((OP)->ob_type) | |
577 | #define _Py_INC_TPFREES(OP) (OP)->ob_type->tp_frees++ | |
578 | #define _Py_DEC_TPFREES(OP) (OP)->ob_type->tp_frees-- | |
579 | #define _Py_COUNT_ALLOCS_COMMA , | |
580 | #else | |
581 | #define _Py_INC_TPALLOCS(OP) | |
582 | #define _Py_INC_TPFREES(OP) | |
583 | #define _Py_DEC_TPFREES(OP) | |
584 | #define _Py_COUNT_ALLOCS_COMMA | |
585 | #endif /* COUNT_ALLOCS */ | |
586 | ||
587 | #ifdef Py_TRACE_REFS | |
588 | /* Py_TRACE_REFS is such major surgery that we call external routines. */ | |
589 | PyAPI_FUNC(void) _Py_NewReference(PyObject *); | |
590 | PyAPI_FUNC(void) _Py_ForgetReference(PyObject *); | |
591 | PyAPI_FUNC(void) _Py_Dealloc(PyObject *); | |
592 | PyAPI_FUNC(void) _Py_PrintReferences(FILE *); | |
593 | PyAPI_FUNC(void) _Py_PrintReferenceAddresses(FILE *); | |
594 | PyAPI_FUNC(void) _Py_AddToAllObjects(PyObject *, int force); | |
595 | ||
596 | #else | |
597 | /* Without Py_TRACE_REFS, there's little enough to do that we expand code | |
598 | * inline. | |
599 | */ | |
600 | #define _Py_NewReference(op) ( \ | |
601 | _Py_INC_TPALLOCS(op) _Py_COUNT_ALLOCS_COMMA \ | |
602 | _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \ | |
603 | (op)->ob_refcnt = 1) | |
604 | ||
605 | #define _Py_ForgetReference(op) _Py_INC_TPFREES(op) | |
606 | ||
607 | #define _Py_Dealloc(op) ( \ | |
608 | _Py_INC_TPFREES(op) _Py_COUNT_ALLOCS_COMMA \ | |
609 | (*(op)->ob_type->tp_dealloc)((PyObject *)(op))) | |
610 | #endif /* !Py_TRACE_REFS */ | |
611 | ||
612 | #define Py_INCREF(op) ( \ | |
613 | _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \ | |
614 | (op)->ob_refcnt++) | |
615 | ||
616 | #define Py_DECREF(op) \ | |
617 | if (_Py_DEC_REFTOTAL _Py_REF_DEBUG_COMMA \ | |
618 | --(op)->ob_refcnt != 0) \ | |
619 | _Py_CHECK_REFCNT(op) \ | |
620 | else \ | |
621 | _Py_Dealloc((PyObject *)(op)) | |
622 | ||
623 | #define Py_CLEAR(op) \ | |
624 | do { \ | |
625 | if (op) { \ | |
626 | PyObject *tmp = (PyObject *)(op); \ | |
627 | (op) = NULL; \ | |
628 | Py_DECREF(tmp); \ | |
629 | } \ | |
630 | } while (0) | |
631 | ||
632 | /* Macros to use in case the object pointer may be NULL: */ | |
633 | #define Py_XINCREF(op) if ((op) == NULL) ; else Py_INCREF(op) | |
634 | #define Py_XDECREF(op) if ((op) == NULL) ; else Py_DECREF(op) | |
635 | ||
636 | /* | |
637 | These are provided as conveniences to Python runtime embedders, so that | |
638 | they can have object code that is not dependent on Python compilation flags. | |
639 | */ | |
640 | PyAPI_FUNC(void) Py_IncRef(PyObject *); | |
641 | PyAPI_FUNC(void) Py_DecRef(PyObject *); | |
642 | ||
643 | /* | |
644 | _Py_NoneStruct is an object of undefined type which can be used in contexts | |
645 | where NULL (nil) is not suitable (since NULL often means 'error'). | |
646 | ||
647 | Don't forget to apply Py_INCREF() when returning this value!!! | |
648 | */ | |
649 | PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */ | |
650 | #define Py_None (&_Py_NoneStruct) | |
651 | ||
652 | /* Macro for returning Py_None from a function */ | |
653 | #define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None | |
654 | ||
655 | /* | |
656 | Py_NotImplemented is a singleton used to signal that an operation is | |
657 | not implemented for a given type combination. | |
658 | */ | |
659 | PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */ | |
660 | #define Py_NotImplemented (&_Py_NotImplementedStruct) | |
661 | ||
662 | /* Rich comparison opcodes */ | |
663 | #define Py_LT 0 | |
664 | #define Py_LE 1 | |
665 | #define Py_EQ 2 | |
666 | #define Py_NE 3 | |
667 | #define Py_GT 4 | |
668 | #define Py_GE 5 | |
669 | ||
670 | /* Maps Py_LT to Py_GT, ..., Py_GE to Py_LE. | |
671 | * Defined in object.c. | |
672 | */ | |
673 | PyAPI_DATA(int) _Py_SwappedOp[]; | |
674 | ||
675 | /* | |
676 | Define staticforward and statichere for source compatibility with old | |
677 | C extensions. | |
678 | ||
679 | The staticforward define was needed to support certain broken C | |
680 | compilers (notably SCO ODT 3.0, perhaps early AIX as well) botched the | |
681 | static keyword when it was used with a forward declaration of a static | |
682 | initialized structure. Standard C allows the forward declaration with | |
683 | static, and we've decided to stop catering to broken C compilers. | |
684 | (In fact, we expect that the compilers are all fixed eight years later.) | |
685 | */ | |
686 | ||
687 | #define staticforward static | |
688 | #define statichere static | |
689 | ||
690 | ||
691 | /* | |
692 | More conventions | |
693 | ================ | |
694 | ||
695 | Argument Checking | |
696 | ----------------- | |
697 | ||
698 | Functions that take objects as arguments normally don't check for nil | |
699 | arguments, but they do check the type of the argument, and return an | |
700 | error if the function doesn't apply to the type. | |
701 | ||
702 | Failure Modes | |
703 | ------------- | |
704 | ||
705 | Functions may fail for a variety of reasons, including running out of | |
706 | memory. This is communicated to the caller in two ways: an error string | |
707 | is set (see errors.h), and the function result differs: functions that | |
708 | normally return a pointer return NULL for failure, functions returning | |
709 | an integer return -1 (which could be a legal return value too!), and | |
710 | other functions return 0 for success and -1 for failure. | |
711 | Callers should always check for errors before using the result. If | |
712 | an error was set, the caller must either explicitly clear it, or pass | |
713 | the error on to its caller. | |
714 | ||
715 | Reference Counts | |
716 | ---------------- | |
717 | ||
718 | It takes a while to get used to the proper usage of reference counts. | |
719 | ||
720 | Functions that create an object set the reference count to 1; such new | |
721 | objects must be stored somewhere or destroyed again with Py_DECREF(). | |
722 | Some functions that 'store' objects, such as PyTuple_SetItem() and | |
723 | PyList_SetItem(), | |
724 | don't increment the reference count of the object, since the most | |
725 | frequent use is to store a fresh object. Functions that 'retrieve' | |
726 | objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also | |
727 | don't increment | |
728 | the reference count, since most frequently the object is only looked at | |
729 | quickly. Thus, to retrieve an object and store it again, the caller | |
730 | must call Py_INCREF() explicitly. | |
731 | ||
732 | NOTE: functions that 'consume' a reference count, like | |
733 | PyList_SetItem(), consume the reference even if the object wasn't | |
734 | successfully stored, to simplify error handling. | |
735 | ||
736 | It seems attractive to make other functions that take an object as | |
737 | argument consume a reference count; however, this may quickly get | |
738 | confusing (even the current practice is already confusing). Consider | |
739 | it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at | |
740 | times. | |
741 | */ | |
742 | ||
743 | ||
744 | /* Trashcan mechanism, thanks to Christian Tismer. | |
745 | ||
746 | When deallocating a container object, it's possible to trigger an unbounded | |
747 | chain of deallocations, as each Py_DECREF in turn drops the refcount on "the | |
748 | next" object in the chain to 0. This can easily lead to stack faults, and | |
749 | especially in threads (which typically have less stack space to work with). | |
750 | ||
751 | A container object that participates in cyclic gc can avoid this by | |
752 | bracketing the body of its tp_dealloc function with a pair of macros: | |
753 | ||
754 | static void | |
755 | mytype_dealloc(mytype *p) | |
756 | { | |
757 | ... declarations go here ... | |
758 | ||
759 | PyObject_GC_UnTrack(p); // must untrack first | |
760 | Py_TRASHCAN_SAFE_BEGIN(p) | |
761 | ... The body of the deallocator goes here, including all calls ... | |
762 | ... to Py_DECREF on contained objects. ... | |
763 | Py_TRASHCAN_SAFE_END(p) | |
764 | } | |
765 | ||
766 | CAUTION: Never return from the middle of the body! If the body needs to | |
767 | "get out early", put a label immediately before the Py_TRASHCAN_SAFE_END | |
768 | call, and goto it. Else the call-depth counter (see below) will stay | |
769 | above 0 forever, and the trashcan will never get emptied. | |
770 | ||
771 | How it works: The BEGIN macro increments a call-depth counter. So long | |
772 | as this counter is small, the body of the deallocator is run directly without | |
773 | further ado. But if the counter gets large, it instead adds p to a list of | |
774 | objects to be deallocated later, skips the body of the deallocator, and | |
775 | resumes execution after the END macro. The tp_dealloc routine then returns | |
776 | without deallocating anything (and so unbounded call-stack depth is avoided). | |
777 | ||
778 | When the call stack finishes unwinding again, code generated by the END macro | |
779 | notices this, and calls another routine to deallocate all the objects that | |
780 | may have been added to the list of deferred deallocations. In effect, a | |
781 | chain of N deallocations is broken into N / PyTrash_UNWIND_LEVEL pieces, | |
782 | with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL. | |
783 | */ | |
784 | ||
785 | PyAPI_FUNC(void) _PyTrash_deposit_object(PyObject*); | |
786 | PyAPI_FUNC(void) _PyTrash_destroy_chain(void); | |
787 | PyAPI_DATA(int) _PyTrash_delete_nesting; | |
788 | PyAPI_DATA(PyObject *) _PyTrash_delete_later; | |
789 | ||
790 | #define PyTrash_UNWIND_LEVEL 50 | |
791 | ||
792 | #define Py_TRASHCAN_SAFE_BEGIN(op) \ | |
793 | if (_PyTrash_delete_nesting < PyTrash_UNWIND_LEVEL) { \ | |
794 | ++_PyTrash_delete_nesting; | |
795 | /* The body of the deallocator is here. */ | |
796 | #define Py_TRASHCAN_SAFE_END(op) \ | |
797 | --_PyTrash_delete_nesting; \ | |
798 | if (_PyTrash_delete_later && _PyTrash_delete_nesting <= 0) \ | |
799 | _PyTrash_destroy_chain(); \ | |
800 | } \ | |
801 | else \ | |
802 | _PyTrash_deposit_object((PyObject*)op); | |
803 | ||
804 | #ifdef __cplusplus | |
805 | } | |
806 | #endif | |
807 | #endif /* !Py_OBJECT_H */ |