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