1 #ifndef Py_OBJECT_H
2 #define Py_OBJECT_H
3
4 #include "pymem.h" /* _Py_tracemalloc_config */
5
6 #ifdef __cplusplus
7 extern "C" {
8 #endif
9
10
11 /* Object and type object interface */
12
13 /*
14 Objects are structures allocated on the heap. Special rules apply to
15 the use of objects to ensure they are properly garbage-collected.
16 Objects are never allocated statically or on the stack; they must be
17 accessed through special macros and functions only. (Type objects are
18 exceptions to the first rule; the standard types are represented by
19 statically initialized type objects, although work on type/class unification
20 for Python 2.2 made it possible to have heap-allocated type objects too).
21
22 An object has a 'reference count' that is increased or decreased when a
23 pointer to the object is copied or deleted; when the reference count
24 reaches zero there are no references to the object left and it can be
25 removed from the heap.
26
27 An object has a 'type' that determines what it represents and what kind
28 of data it contains. An object's type is fixed when it is created.
29 Types themselves are represented as objects; an object contains a
30 pointer to the corresponding type object. The type itself has a type
31 pointer pointing to the object representing the type 'type', which
32 contains a pointer to itself!.
33
34 Objects do not float around in memory; once allocated an object keeps
35 the same size and address. Objects that must hold variable-size data
36 can contain pointers to variable-size parts of the object. Not all
37 objects of the same type have the same size; but the size cannot change
38 after allocation. (These restrictions are made so a reference to an
39 object can be simply a pointer -- moving an object would require
40 updating all the pointers, and changing an object's size would require
41 moving it if there was another object right next to it.)
42
43 Objects are always accessed through pointers of the type 'PyObject *'.
44 The type 'PyObject' is a structure that only contains the reference count
45 and the type pointer. The actual memory allocated for an object
46 contains other data that can only be accessed after casting the pointer
47 to a pointer to a longer structure type. This longer type must start
48 with the reference count and type fields; the macro PyObject_HEAD should be
49 used for this (to accommodate for future changes). The implementation
50 of a particular object type can cast the object pointer to the proper
51 type and back.
52
53 A standard interface exists for objects that contain an array of items
54 whose size is determined when the object is allocated.
55 */
56
57 /* Py_DEBUG implies Py_REF_DEBUG. */
58 #if defined(Py_DEBUG) && !defined(Py_REF_DEBUG)
59 #define Py_REF_DEBUG
60 #endif
61
62 #if defined(Py_LIMITED_API) && defined(Py_REF_DEBUG)
63 #error Py_LIMITED_API is incompatible with Py_DEBUG, Py_TRACE_REFS, and Py_REF_DEBUG
64 #endif
65
66
67 #ifdef Py_TRACE_REFS
68 /* Define pointers to support a doubly-linked list of all live heap objects. */
69 #define _PyObject_HEAD_EXTRA \
70 struct _object *_ob_next; \
71 struct _object *_ob_prev;
72
73 #define _PyObject_EXTRA_INIT 0, 0,
74
75 #else
76 #define _PyObject_HEAD_EXTRA
77 #define _PyObject_EXTRA_INIT
78 #endif
79
80 /* PyObject_HEAD defines the initial segment of every PyObject. */
81 #define PyObject_HEAD PyObject ob_base;
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 PyVarObject ob_base;
97 #define Py_INVALID_SIZE (Py_ssize_t)-1
98
99 /* Nothing is actually declared to be a PyObject, but every pointer to
100 * a Python object can be cast to a PyObject*. This is inheritance built
101 * by hand. Similarly every pointer to a variable-size Python object can,
102 * in addition, be cast to PyVarObject*.
103 */
104 typedef struct _object {
105 _PyObject_HEAD_EXTRA
106 Py_ssize_t ob_refcnt;
107 struct _typeobject *ob_type;
108 } PyObject;
109
110 /* Cast argument to PyObject* type. */
111 #define _PyObject_CAST(op) ((PyObject*)(op))
112
113 typedef struct {
114 PyObject ob_base;
115 Py_ssize_t ob_size; /* Number of items in variable part */
116 } PyVarObject;
117
118 /* Cast argument to PyVarObject* type. */
119 #define _PyVarObject_CAST(op) ((PyVarObject*)(op))
120
121 #define Py_REFCNT(ob) (_PyObject_CAST(ob)->ob_refcnt)
122 #define Py_TYPE(ob) (_PyObject_CAST(ob)->ob_type)
123 #define Py_SIZE(ob) (_PyVarObject_CAST(ob)->ob_size)
124
125 /*
126 Type objects contain a string containing the type name (to help somewhat
127 in debugging), the allocation parameters (see PyObject_New() and
128 PyObject_NewVar()),
129 and methods for accessing objects of the type. Methods are optional, a
130 nil pointer meaning that particular kind of access is not available for
131 this type. The Py_DECREF() macro uses the tp_dealloc method without
132 checking for a nil pointer; it should always be implemented except if
133 the implementation can guarantee that the reference count will never
134 reach zero (e.g., for statically allocated type objects).
135
136 NB: the methods for certain type groups are now contained in separate
137 method blocks.
138 */
139
140 typedef PyObject * (*unaryfunc)(PyObject *);
141 typedef PyObject * (*binaryfunc)(PyObject *, PyObject *);
142 typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *);
143 typedef int (*inquiry)(PyObject *);
144 typedef Py_ssize_t (*lenfunc)(PyObject *);
145 typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t);
146 typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t);
147 typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *);
148 typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *);
149 typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *);
150
151 typedef int (*objobjproc)(PyObject *, PyObject *);
152 typedef int (*visitproc)(PyObject *, void *);
153 typedef int (*traverseproc)(PyObject *, visitproc, void *);
154
155
156 typedef void (*freefunc)(void *);
157 typedef void (*destructor)(PyObject *);
158 typedef PyObject *(*getattrfunc)(PyObject *, char *);
159 typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
160 typedef int (*setattrfunc)(PyObject *, char *, PyObject *);
161 typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *);
162 typedef PyObject *(*reprfunc)(PyObject *);
163 typedef Py_hash_t (*hashfunc)(PyObject *);
164 typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int);
165 typedef PyObject *(*getiterfunc) (PyObject *);
166 typedef PyObject *(*iternextfunc) (PyObject *);
167 typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *);
168 typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *);
169 typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
170 typedef PyObject *(*newfunc)(struct _typeobject *, PyObject *, PyObject *);
171 typedef PyObject *(*allocfunc)(struct _typeobject *, Py_ssize_t);
172
173 #ifdef Py_LIMITED_API
174 /* In Py_LIMITED_API, PyTypeObject is an opaque structure. */
175 typedef struct _typeobject PyTypeObject;
176 #else
177 /* PyTypeObject is defined in cpython/object.h */
178 #endif
179
180 typedef struct{
181 int slot; /* slot id, see below */
182 void *pfunc; /* function pointer */
183 } PyType_Slot;
184
185 typedef struct{
186 const char* name;
187 int basicsize;
188 int itemsize;
189 unsigned int flags;
190 PyType_Slot *slots; /* terminated by slot==0. */
191 } PyType_Spec;
192
193 PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*);
194 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
195 PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*);
196 #endif
197 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000
198 PyAPI_FUNC(void*) PyType_GetSlot(struct _typeobject*, int);
199 #endif
200
201 /* Generic type check */
202 PyAPI_FUNC(int) PyType_IsSubtype(struct _typeobject *, struct _typeobject *);
203 #define PyObject_TypeCheck(ob, tp) \
204 (Py_TYPE(ob) == (tp) || PyType_IsSubtype(Py_TYPE(ob), (tp)))
205
206 PyAPI_DATA(struct _typeobject) PyType_Type; /* built-in 'type' */
207 PyAPI_DATA(struct _typeobject) PyBaseObject_Type; /* built-in 'object' */
208 PyAPI_DATA(struct _typeobject) PySuper_Type; /* built-in 'super' */
209
210 PyAPI_FUNC(unsigned long) PyType_GetFlags(struct _typeobject*);
211
212 #define PyType_Check(op) \
213 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS)
214 #define PyType_CheckExact(op) (Py_TYPE(op) == &PyType_Type)
215
216 PyAPI_FUNC(int) PyType_Ready(struct _typeobject *);
217 PyAPI_FUNC(PyObject *) PyType_GenericAlloc(struct _typeobject *, Py_ssize_t);
218 PyAPI_FUNC(PyObject *) PyType_GenericNew(struct _typeobject *,
219 PyObject *, PyObject *);
220 PyAPI_FUNC(unsigned int) PyType_ClearCache(void);
221 PyAPI_FUNC(void) PyType_Modified(struct _typeobject *);
222
223 /* Generic operations on objects */
224 PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
225 PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
226 PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *);
227 PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *);
228 PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
229 PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
230 PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *);
231 PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *);
232 PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *);
233 PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
234 PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
235 PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
236 PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *);
237 PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
238 PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *,
239 PyObject *, PyObject *);
240 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
241 PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *);
242 #endif
243 PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *);
244 PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *);
245 PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
246 PyAPI_FUNC(int) PyObject_Not(PyObject *);
247 PyAPI_FUNC(int) PyCallable_Check(PyObject *);
248 PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
249
250 /* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a
251 list of strings. PyObject_Dir(NULL) is like builtins.dir(),
252 returning the names of the current locals. In this case, if there are
253 no current locals, NULL is returned, and PyErr_Occurred() is false.
254 */
255 PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
256
257
258 /* Helpers for printing recursive container types */
259 PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
260 PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
261
262 /* Flag bits for printing: */
263 #define Py_PRINT_RAW 1 /* No string quotes etc. */
264
265 /*
266 Type flags (tp_flags)
267
268 These flags are used to change expected features and behavior for a
269 particular type.
270
271 Arbitration of the flag bit positions will need to be coordinated among
272 all extension writers who publicly release their extensions (this will
273 be fewer than you might expect!).
274
275 Most flags were removed as of Python 3.0 to make room for new flags. (Some
276 flags are not for backwards compatibility but to indicate the presence of an
277 optional feature; these flags remain of course.)
278
279 Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
280
281 Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
282 given type object has a specified feature.
283 */
284
285 /* Set if the type object is dynamically allocated */
286 #define Py_TPFLAGS_HEAPTYPE (1UL << 9)
287
288 /* Set if the type allows subclassing */
289 #define Py_TPFLAGS_BASETYPE (1UL << 10)
290
291 /* Set if the type implements the vectorcall protocol (PEP 590) */
292 #ifndef Py_LIMITED_API
293 #define _Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11)
294 #endif
295
296 /* Set if the type is 'ready' -- fully initialized */
297 #define Py_TPFLAGS_READY (1UL << 12)
298
299 /* Set while the type is being 'readied', to prevent recursive ready calls */
300 #define Py_TPFLAGS_READYING (1UL << 13)
301
302 /* Objects support garbage collection (see objimpl.h) */
303 #define Py_TPFLAGS_HAVE_GC (1UL << 14)
304
305 /* These two bits are preserved for Stackless Python, next after this is 17 */
306 #ifdef STACKLESS
307 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15)
308 #else
309 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
310 #endif
311
312 /* Objects behave like an unbound method */
313 #define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17)
314
315 /* Objects support type attribute cache */
316 #define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18)
317 #define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19)
318
319 /* Type is abstract and cannot be instantiated */
320 #define Py_TPFLAGS_IS_ABSTRACT (1UL << 20)
321
322 /* These flags are used to determine if a type is a subclass. */
323 #define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24)
324 #define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25)
325 #define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26)
326 #define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27)
327 #define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28)
328 #define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29)
329 #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30)
330 #define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31)
331
332 #define Py_TPFLAGS_DEFAULT ( \
333 Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
334 Py_TPFLAGS_HAVE_VERSION_TAG | \
335 0)
336
337 /* NOTE: The following flags reuse lower bits (removed as part of the
338 * Python 3.0 transition). */
339
340 /* The following flag is kept for compatibility. Starting with 3.8,
341 * binary compatibility of C extensions accross feature releases of
342 * Python is not supported anymore, except when using the stable ABI.
343 */
344
345 /* Type structure has tp_finalize member (3.4) */
346 #define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0)
347
348 #ifdef Py_LIMITED_API
349 # define PyType_HasFeature(t,f) ((PyType_GetFlags(t) & (f)) != 0)
350 #endif
351 #define PyType_FastSubclass(t,f) PyType_HasFeature(t,f)
352
353
354 /*
355 The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
356 reference counts. Py_DECREF calls the object's deallocator function when
357 the refcount falls to 0; for
358 objects that don't contain references to other objects or heap memory
359 this can be the standard function free(). Both macros can be used
360 wherever a void expression is allowed. The argument must not be a
361 NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead.
362 The macro _Py_NewReference(op) initialize reference counts to 1, and
363 in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
364 bookkeeping appropriate to the special build.
365
366 We assume that the reference count field can never overflow; this can
367 be proven when the size of the field is the same as the pointer size, so
368 we ignore the possibility. Provided a C int is at least 32 bits (which
369 is implicitly assumed in many parts of this code), that's enough for
370 about 2**31 references to an object.
371
372 XXX The following became out of date in Python 2.2, but I'm not sure
373 XXX what the full truth is now. Certainly, heap-allocated type objects
374 XXX can and should be deallocated.
375 Type objects should never be deallocated; the type pointer in an object
376 is not considered to be a reference to the type object, to save
377 complications in the deallocation function. (This is actually a
378 decision that's up to the implementer of each new type so if you want,
379 you can count such references to the type object.)
380 */
381
382 /* First define a pile of simple helper macros, one set per special
383 * build symbol. These either expand to the obvious things, or to
384 * nothing at all when the special mode isn't in effect. The main
385 * macros can later be defined just once then, yet expand to different
386 * things depending on which special build options are and aren't in effect.
387 * Trust me <wink>: while painful, this is 20x easier to understand than,
388 * e.g, defining _Py_NewReference five different times in a maze of nested
389 * #ifdefs (we used to do that -- it was impenetrable).
390 */
391 #ifdef Py_REF_DEBUG
392 PyAPI_DATA(Py_ssize_t) _Py_RefTotal;
393 PyAPI_FUNC(void) _Py_NegativeRefcount(const char *filename, int lineno,
394 PyObject *op);
395 PyAPI_FUNC(Py_ssize_t) _Py_GetRefTotal(void);
396 #define _Py_INC_REFTOTAL _Py_RefTotal++
397 #define _Py_DEC_REFTOTAL _Py_RefTotal--
398
399 /* Py_REF_DEBUG also controls the display of refcounts and memory block
400 * allocations at the interactive prompt and at interpreter shutdown
401 */
402 PyAPI_FUNC(void) _PyDebug_PrintTotalRefs(void);
403 #else
404 #define _Py_INC_REFTOTAL
405 #define _Py_DEC_REFTOTAL
406 #endif /* Py_REF_DEBUG */
407
408 #ifdef COUNT_ALLOCS
409 PyAPI_FUNC(void) _Py_inc_count(struct _typeobject *);
410 PyAPI_FUNC(void) _Py_dec_count(struct _typeobject *);
411 #define _Py_INC_TPALLOCS(OP) _Py_inc_count(Py_TYPE(OP))
412 #define _Py_INC_TPFREES(OP) _Py_dec_count(Py_TYPE(OP))
413 #define _Py_DEC_TPFREES(OP) Py_TYPE(OP)->tp_frees--
414 #define _Py_COUNT_ALLOCS_COMMA ,
415 #else
416 #define _Py_INC_TPALLOCS(OP)
417 #define _Py_INC_TPFREES(OP)
418 #define _Py_DEC_TPFREES(OP)
419 #define _Py_COUNT_ALLOCS_COMMA
420 #endif /* COUNT_ALLOCS */
421
422 /* Update the Python traceback of an object. This function must be called
423 when a memory block is reused from a free list. */
424 PyAPI_FUNC(int) _PyTraceMalloc_NewReference(PyObject *op);
425
426 #ifdef Py_TRACE_REFS
427 /* Py_TRACE_REFS is such major surgery that we call external routines. */
428 PyAPI_FUNC(void) _Py_NewReference(PyObject *);
429 PyAPI_FUNC(void) _Py_ForgetReference(PyObject *);
430 PyAPI_FUNC(void) _Py_PrintReferences(FILE *);
431 PyAPI_FUNC(void) _Py_PrintReferenceAddresses(FILE *);
432 PyAPI_FUNC(void) _Py_AddToAllObjects(PyObject *, int force);
433 #else
434 /* Without Py_TRACE_REFS, there's little enough to do that we expand code
435 inline. */
_Py_NewReference(PyObject * op)436 static inline void _Py_NewReference(PyObject *op)
437 {
438 if (_Py_tracemalloc_config.tracing) {
439 _PyTraceMalloc_NewReference(op);
440 }
441 _Py_INC_TPALLOCS(op);
442 _Py_INC_REFTOTAL;
443 Py_REFCNT(op) = 1;
444 }
445
_Py_ForgetReference(PyObject * op)446 static inline void _Py_ForgetReference(PyObject *op)
447 {
448 (void)op; /* may be unused, shut up -Wunused-parameter */
449 _Py_INC_TPFREES(op);
450 }
451 #endif /* !Py_TRACE_REFS */
452
453
454 PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
455
_Py_INCREF(PyObject * op)456 static inline void _Py_INCREF(PyObject *op)
457 {
458 _Py_INC_REFTOTAL;
459 op->ob_refcnt++;
460 }
461
462 #define Py_INCREF(op) _Py_INCREF(_PyObject_CAST(op))
463
_Py_DECREF(const char * filename,int lineno,PyObject * op)464 static inline void _Py_DECREF(const char *filename, int lineno,
465 PyObject *op)
466 {
467 (void)filename; /* may be unused, shut up -Wunused-parameter */
468 (void)lineno; /* may be unused, shut up -Wunused-parameter */
469 _Py_DEC_REFTOTAL;
470 if (--op->ob_refcnt != 0) {
471 #ifdef Py_REF_DEBUG
472 if (op->ob_refcnt < 0) {
473 _Py_NegativeRefcount(filename, lineno, op);
474 }
475 #endif
476 }
477 else {
478 _Py_Dealloc(op);
479 }
480 }
481
482 #define Py_DECREF(op) _Py_DECREF(__FILE__, __LINE__, _PyObject_CAST(op))
483
484
485 /* Safely decref `op` and set `op` to NULL, especially useful in tp_clear
486 * and tp_dealloc implementations.
487 *
488 * Note that "the obvious" code can be deadly:
489 *
490 * Py_XDECREF(op);
491 * op = NULL;
492 *
493 * Typically, `op` is something like self->containee, and `self` is done
494 * using its `containee` member. In the code sequence above, suppose
495 * `containee` is non-NULL with a refcount of 1. Its refcount falls to
496 * 0 on the first line, which can trigger an arbitrary amount of code,
497 * possibly including finalizers (like __del__ methods or weakref callbacks)
498 * coded in Python, which in turn can release the GIL and allow other threads
499 * to run, etc. Such code may even invoke methods of `self` again, or cause
500 * cyclic gc to trigger, but-- oops! --self->containee still points to the
501 * object being torn down, and it may be in an insane state while being torn
502 * down. This has in fact been a rich historic source of miserable (rare &
503 * hard-to-diagnose) segfaulting (and other) bugs.
504 *
505 * The safe way is:
506 *
507 * Py_CLEAR(op);
508 *
509 * That arranges to set `op` to NULL _before_ decref'ing, so that any code
510 * triggered as a side-effect of `op` getting torn down no longer believes
511 * `op` points to a valid object.
512 *
513 * There are cases where it's safe to use the naive code, but they're brittle.
514 * For example, if `op` points to a Python integer, you know that destroying
515 * one of those can't cause problems -- but in part that relies on that
516 * Python integers aren't currently weakly referencable. Best practice is
517 * to use Py_CLEAR() even if you can't think of a reason for why you need to.
518 */
519 #define Py_CLEAR(op) \
520 do { \
521 PyObject *_py_tmp = _PyObject_CAST(op); \
522 if (_py_tmp != NULL) { \
523 (op) = NULL; \
524 Py_DECREF(_py_tmp); \
525 } \
526 } while (0)
527
528 /* Function to use in case the object pointer can be NULL: */
_Py_XINCREF(PyObject * op)529 static inline void _Py_XINCREF(PyObject *op)
530 {
531 if (op != NULL) {
532 Py_INCREF(op);
533 }
534 }
535
536 #define Py_XINCREF(op) _Py_XINCREF(_PyObject_CAST(op))
537
_Py_XDECREF(PyObject * op)538 static inline void _Py_XDECREF(PyObject *op)
539 {
540 if (op != NULL) {
541 Py_DECREF(op);
542 }
543 }
544
545 #define Py_XDECREF(op) _Py_XDECREF(_PyObject_CAST(op))
546
547 /*
548 These are provided as conveniences to Python runtime embedders, so that
549 they can have object code that is not dependent on Python compilation flags.
550 */
551 PyAPI_FUNC(void) Py_IncRef(PyObject *);
552 PyAPI_FUNC(void) Py_DecRef(PyObject *);
553
554 /*
555 _Py_NoneStruct is an object of undefined type which can be used in contexts
556 where NULL (nil) is not suitable (since NULL often means 'error').
557
558 Don't forget to apply Py_INCREF() when returning this value!!!
559 */
560 PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
561 #define Py_None (&_Py_NoneStruct)
562
563 /* Macro for returning Py_None from a function */
564 #define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None
565
566 /*
567 Py_NotImplemented is a singleton used to signal that an operation is
568 not implemented for a given type combination.
569 */
570 PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
571 #define Py_NotImplemented (&_Py_NotImplementedStruct)
572
573 /* Macro for returning Py_NotImplemented from a function */
574 #define Py_RETURN_NOTIMPLEMENTED \
575 return Py_INCREF(Py_NotImplemented), Py_NotImplemented
576
577 /* Rich comparison opcodes */
578 #define Py_LT 0
579 #define Py_LE 1
580 #define Py_EQ 2
581 #define Py_NE 3
582 #define Py_GT 4
583 #define Py_GE 5
584
585 /*
586 * Macro for implementing rich comparisons
587 *
588 * Needs to be a macro because any C-comparable type can be used.
589 */
590 #define Py_RETURN_RICHCOMPARE(val1, val2, op) \
591 do { \
592 switch (op) { \
593 case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
594 case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
595 case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
596 case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
597 case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
598 case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
599 default: \
600 Py_UNREACHABLE(); \
601 } \
602 } while (0)
603
604
605 /*
606 More conventions
607 ================
608
609 Argument Checking
610 -----------------
611
612 Functions that take objects as arguments normally don't check for nil
613 arguments, but they do check the type of the argument, and return an
614 error if the function doesn't apply to the type.
615
616 Failure Modes
617 -------------
618
619 Functions may fail for a variety of reasons, including running out of
620 memory. This is communicated to the caller in two ways: an error string
621 is set (see errors.h), and the function result differs: functions that
622 normally return a pointer return NULL for failure, functions returning
623 an integer return -1 (which could be a legal return value too!), and
624 other functions return 0 for success and -1 for failure.
625 Callers should always check for errors before using the result. If
626 an error was set, the caller must either explicitly clear it, or pass
627 the error on to its caller.
628
629 Reference Counts
630 ----------------
631
632 It takes a while to get used to the proper usage of reference counts.
633
634 Functions that create an object set the reference count to 1; such new
635 objects must be stored somewhere or destroyed again with Py_DECREF().
636 Some functions that 'store' objects, such as PyTuple_SetItem() and
637 PyList_SetItem(),
638 don't increment the reference count of the object, since the most
639 frequent use is to store a fresh object. Functions that 'retrieve'
640 objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
641 don't increment
642 the reference count, since most frequently the object is only looked at
643 quickly. Thus, to retrieve an object and store it again, the caller
644 must call Py_INCREF() explicitly.
645
646 NOTE: functions that 'consume' a reference count, like
647 PyList_SetItem(), consume the reference even if the object wasn't
648 successfully stored, to simplify error handling.
649
650 It seems attractive to make other functions that take an object as
651 argument consume a reference count; however, this may quickly get
652 confusing (even the current practice is already confusing). Consider
653 it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
654 times.
655 */
656
657
658 /* Trashcan mechanism, thanks to Christian Tismer.
659
660 When deallocating a container object, it's possible to trigger an unbounded
661 chain of deallocations, as each Py_DECREF in turn drops the refcount on "the
662 next" object in the chain to 0. This can easily lead to stack overflows,
663 especially in threads (which typically have less stack space to work with).
664
665 A container object can avoid this by bracketing the body of its tp_dealloc
666 function with a pair of macros:
667
668 static void
669 mytype_dealloc(mytype *p)
670 {
671 ... declarations go here ...
672
673 PyObject_GC_UnTrack(p); // must untrack first
674 Py_TRASHCAN_BEGIN(p, mytype_dealloc)
675 ... The body of the deallocator goes here, including all calls ...
676 ... to Py_DECREF on contained objects. ...
677 Py_TRASHCAN_END // there should be no code after this
678 }
679
680 CAUTION: Never return from the middle of the body! If the body needs to
681 "get out early", put a label immediately before the Py_TRASHCAN_END
682 call, and goto it. Else the call-depth counter (see below) will stay
683 above 0 forever, and the trashcan will never get emptied.
684
685 How it works: The BEGIN macro increments a call-depth counter. So long
686 as this counter is small, the body of the deallocator is run directly without
687 further ado. But if the counter gets large, it instead adds p to a list of
688 objects to be deallocated later, skips the body of the deallocator, and
689 resumes execution after the END macro. The tp_dealloc routine then returns
690 without deallocating anything (and so unbounded call-stack depth is avoided).
691
692 When the call stack finishes unwinding again, code generated by the END macro
693 notices this, and calls another routine to deallocate all the objects that
694 may have been added to the list of deferred deallocations. In effect, a
695 chain of N deallocations is broken into (N-1)/(PyTrash_UNWIND_LEVEL-1) pieces,
696 with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL.
697
698 Since the tp_dealloc of a subclass typically calls the tp_dealloc of the base
699 class, we need to ensure that the trashcan is only triggered on the tp_dealloc
700 of the actual class being deallocated. Otherwise we might end up with a
701 partially-deallocated object. To check this, the tp_dealloc function must be
702 passed as second argument to Py_TRASHCAN_BEGIN().
703 */
704
705 /* The new thread-safe private API, invoked by the macros below. */
706 PyAPI_FUNC(void) _PyTrash_thread_deposit_object(PyObject*);
707 PyAPI_FUNC(void) _PyTrash_thread_destroy_chain(void);
708
709 #define PyTrash_UNWIND_LEVEL 50
710
711 #define Py_TRASHCAN_BEGIN_CONDITION(op, cond) \
712 do { \
713 PyThreadState *_tstate = NULL; \
714 /* If "cond" is false, then _tstate remains NULL and the deallocator \
715 * is run normally without involving the trashcan */ \
716 if (cond) { \
717 _tstate = PyThreadState_GET(); \
718 if (_tstate->trash_delete_nesting >= PyTrash_UNWIND_LEVEL) { \
719 /* Store the object (to be deallocated later) and jump past \
720 * Py_TRASHCAN_END, skipping the body of the deallocator */ \
721 _PyTrash_thread_deposit_object(_PyObject_CAST(op)); \
722 break; \
723 } \
724 ++_tstate->trash_delete_nesting; \
725 }
726 /* The body of the deallocator is here. */
727 #define Py_TRASHCAN_END \
728 if (_tstate) { \
729 --_tstate->trash_delete_nesting; \
730 if (_tstate->trash_delete_later && _tstate->trash_delete_nesting <= 0) \
731 _PyTrash_thread_destroy_chain(); \
732 } \
733 } while (0);
734
735 #define Py_TRASHCAN_BEGIN(op, dealloc) Py_TRASHCAN_BEGIN_CONDITION(op, \
736 Py_TYPE(op)->tp_dealloc == (destructor)(dealloc))
737
738 /* For backwards compatibility, these macros enable the trashcan
739 * unconditionally */
740 #define Py_TRASHCAN_SAFE_BEGIN(op) Py_TRASHCAN_BEGIN_CONDITION(op, 1)
741 #define Py_TRASHCAN_SAFE_END(op) Py_TRASHCAN_END
742
743
744 #ifndef Py_LIMITED_API
745 # define Py_CPYTHON_OBJECT_H
746 # include "cpython/object.h"
747 # undef Py_CPYTHON_OBJECT_H
748 #endif
749
750 #ifdef __cplusplus
751 }
752 #endif
753 #endif /* !Py_OBJECT_H */
754