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