jpayne@69: #ifndef Py_OBJECT_H jpayne@69: #define Py_OBJECT_H jpayne@69: jpayne@69: #include "pymem.h" /* _Py_tracemalloc_config */ jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: extern "C" { jpayne@69: #endif jpayne@69: jpayne@69: jpayne@69: /* Object and type object interface */ jpayne@69: jpayne@69: /* jpayne@69: Objects are structures allocated on the heap. Special rules apply to jpayne@69: the use of objects to ensure they are properly garbage-collected. jpayne@69: Objects are never allocated statically or on the stack; they must be jpayne@69: accessed through special macros and functions only. (Type objects are jpayne@69: exceptions to the first rule; the standard types are represented by jpayne@69: statically initialized type objects, although work on type/class unification jpayne@69: for Python 2.2 made it possible to have heap-allocated type objects too). jpayne@69: jpayne@69: An object has a 'reference count' that is increased or decreased when a jpayne@69: pointer to the object is copied or deleted; when the reference count jpayne@69: reaches zero there are no references to the object left and it can be jpayne@69: removed from the heap. jpayne@69: jpayne@69: An object has a 'type' that determines what it represents and what kind jpayne@69: of data it contains. An object's type is fixed when it is created. jpayne@69: Types themselves are represented as objects; an object contains a jpayne@69: pointer to the corresponding type object. The type itself has a type jpayne@69: pointer pointing to the object representing the type 'type', which jpayne@69: contains a pointer to itself!). jpayne@69: jpayne@69: Objects do not float around in memory; once allocated an object keeps jpayne@69: the same size and address. Objects that must hold variable-size data jpayne@69: can contain pointers to variable-size parts of the object. Not all jpayne@69: objects of the same type have the same size; but the size cannot change jpayne@69: after allocation. (These restrictions are made so a reference to an jpayne@69: object can be simply a pointer -- moving an object would require jpayne@69: updating all the pointers, and changing an object's size would require jpayne@69: moving it if there was another object right next to it.) jpayne@69: jpayne@69: Objects are always accessed through pointers of the type 'PyObject *'. jpayne@69: The type 'PyObject' is a structure that only contains the reference count jpayne@69: and the type pointer. The actual memory allocated for an object jpayne@69: contains other data that can only be accessed after casting the pointer jpayne@69: to a pointer to a longer structure type. This longer type must start jpayne@69: with the reference count and type fields; the macro PyObject_HEAD should be jpayne@69: used for this (to accommodate for future changes). The implementation jpayne@69: of a particular object type can cast the object pointer to the proper jpayne@69: type and back. jpayne@69: jpayne@69: A standard interface exists for objects that contain an array of items jpayne@69: whose size is determined when the object is allocated. jpayne@69: */ jpayne@69: jpayne@69: /* Py_DEBUG implies Py_REF_DEBUG. */ jpayne@69: #if defined(Py_DEBUG) && !defined(Py_REF_DEBUG) jpayne@69: #define Py_REF_DEBUG jpayne@69: #endif jpayne@69: jpayne@69: #if defined(Py_LIMITED_API) && defined(Py_REF_DEBUG) jpayne@69: #error Py_LIMITED_API is incompatible with Py_DEBUG, Py_TRACE_REFS, and Py_REF_DEBUG jpayne@69: #endif jpayne@69: jpayne@69: jpayne@69: #ifdef Py_TRACE_REFS jpayne@69: /* Define pointers to support a doubly-linked list of all live heap objects. */ jpayne@69: #define _PyObject_HEAD_EXTRA \ jpayne@69: struct _object *_ob_next; \ jpayne@69: struct _object *_ob_prev; jpayne@69: jpayne@69: #define _PyObject_EXTRA_INIT 0, 0, jpayne@69: jpayne@69: #else jpayne@69: #define _PyObject_HEAD_EXTRA jpayne@69: #define _PyObject_EXTRA_INIT jpayne@69: #endif jpayne@69: jpayne@69: /* PyObject_HEAD defines the initial segment of every PyObject. */ jpayne@69: #define PyObject_HEAD PyObject ob_base; jpayne@69: jpayne@69: #define PyObject_HEAD_INIT(type) \ jpayne@69: { _PyObject_EXTRA_INIT \ jpayne@69: 1, type }, jpayne@69: jpayne@69: #define PyVarObject_HEAD_INIT(type, size) \ jpayne@69: { PyObject_HEAD_INIT(type) size }, jpayne@69: jpayne@69: /* PyObject_VAR_HEAD defines the initial segment of all variable-size jpayne@69: * container objects. These end with a declaration of an array with 1 jpayne@69: * element, but enough space is malloc'ed so that the array actually jpayne@69: * has room for ob_size elements. Note that ob_size is an element count, jpayne@69: * not necessarily a byte count. jpayne@69: */ jpayne@69: #define PyObject_VAR_HEAD PyVarObject ob_base; jpayne@69: #define Py_INVALID_SIZE (Py_ssize_t)-1 jpayne@69: jpayne@69: /* Nothing is actually declared to be a PyObject, but every pointer to jpayne@69: * a Python object can be cast to a PyObject*. This is inheritance built jpayne@69: * by hand. Similarly every pointer to a variable-size Python object can, jpayne@69: * in addition, be cast to PyVarObject*. jpayne@69: */ jpayne@69: typedef struct _object { jpayne@69: _PyObject_HEAD_EXTRA jpayne@69: Py_ssize_t ob_refcnt; jpayne@69: struct _typeobject *ob_type; jpayne@69: } PyObject; jpayne@69: jpayne@69: /* Cast argument to PyObject* type. */ jpayne@69: #define _PyObject_CAST(op) ((PyObject*)(op)) jpayne@69: jpayne@69: typedef struct { jpayne@69: PyObject ob_base; jpayne@69: Py_ssize_t ob_size; /* Number of items in variable part */ jpayne@69: } PyVarObject; jpayne@69: jpayne@69: /* Cast argument to PyVarObject* type. */ jpayne@69: #define _PyVarObject_CAST(op) ((PyVarObject*)(op)) jpayne@69: jpayne@69: #define Py_REFCNT(ob) (_PyObject_CAST(ob)->ob_refcnt) jpayne@69: #define Py_TYPE(ob) (_PyObject_CAST(ob)->ob_type) jpayne@69: #define Py_SIZE(ob) (_PyVarObject_CAST(ob)->ob_size) jpayne@69: jpayne@69: /* jpayne@69: Type objects contain a string containing the type name (to help somewhat jpayne@69: in debugging), the allocation parameters (see PyObject_New() and jpayne@69: PyObject_NewVar()), jpayne@69: and methods for accessing objects of the type. Methods are optional, a jpayne@69: nil pointer meaning that particular kind of access is not available for jpayne@69: this type. The Py_DECREF() macro uses the tp_dealloc method without jpayne@69: checking for a nil pointer; it should always be implemented except if jpayne@69: the implementation can guarantee that the reference count will never jpayne@69: reach zero (e.g., for statically allocated type objects). jpayne@69: jpayne@69: NB: the methods for certain type groups are now contained in separate jpayne@69: method blocks. jpayne@69: */ jpayne@69: jpayne@69: typedef PyObject * (*unaryfunc)(PyObject *); jpayne@69: typedef PyObject * (*binaryfunc)(PyObject *, PyObject *); jpayne@69: typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *); jpayne@69: typedef int (*inquiry)(PyObject *); jpayne@69: typedef Py_ssize_t (*lenfunc)(PyObject *); jpayne@69: typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t); jpayne@69: typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t); jpayne@69: typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *); jpayne@69: typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *); jpayne@69: typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *); jpayne@69: jpayne@69: typedef int (*objobjproc)(PyObject *, PyObject *); jpayne@69: typedef int (*visitproc)(PyObject *, void *); jpayne@69: typedef int (*traverseproc)(PyObject *, visitproc, void *); jpayne@69: jpayne@69: jpayne@69: typedef void (*freefunc)(void *); jpayne@69: typedef void (*destructor)(PyObject *); jpayne@69: typedef PyObject *(*getattrfunc)(PyObject *, char *); jpayne@69: typedef PyObject *(*getattrofunc)(PyObject *, PyObject *); jpayne@69: typedef int (*setattrfunc)(PyObject *, char *, PyObject *); jpayne@69: typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *); jpayne@69: typedef PyObject *(*reprfunc)(PyObject *); jpayne@69: typedef Py_hash_t (*hashfunc)(PyObject *); jpayne@69: typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int); jpayne@69: typedef PyObject *(*getiterfunc) (PyObject *); jpayne@69: typedef PyObject *(*iternextfunc) (PyObject *); jpayne@69: typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *); jpayne@69: typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *); jpayne@69: typedef int (*initproc)(PyObject *, PyObject *, PyObject *); jpayne@69: typedef PyObject *(*newfunc)(struct _typeobject *, PyObject *, PyObject *); jpayne@69: typedef PyObject *(*allocfunc)(struct _typeobject *, Py_ssize_t); jpayne@69: jpayne@69: #ifdef Py_LIMITED_API jpayne@69: /* In Py_LIMITED_API, PyTypeObject is an opaque structure. */ jpayne@69: typedef struct _typeobject PyTypeObject; jpayne@69: #else jpayne@69: /* PyTypeObject is defined in cpython/object.h */ jpayne@69: #endif jpayne@69: jpayne@69: typedef struct{ jpayne@69: int slot; /* slot id, see below */ jpayne@69: void *pfunc; /* function pointer */ jpayne@69: } PyType_Slot; jpayne@69: jpayne@69: typedef struct{ jpayne@69: const char* name; jpayne@69: int basicsize; jpayne@69: int itemsize; jpayne@69: unsigned int flags; jpayne@69: PyType_Slot *slots; /* terminated by slot==0. */ jpayne@69: } PyType_Spec; jpayne@69: jpayne@69: PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*); jpayne@69: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 jpayne@69: PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*); jpayne@69: #endif jpayne@69: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000 jpayne@69: PyAPI_FUNC(void*) PyType_GetSlot(struct _typeobject*, int); jpayne@69: #endif jpayne@69: jpayne@69: /* Generic type check */ jpayne@69: PyAPI_FUNC(int) PyType_IsSubtype(struct _typeobject *, struct _typeobject *); jpayne@69: #define PyObject_TypeCheck(ob, tp) \ jpayne@69: (Py_TYPE(ob) == (tp) || PyType_IsSubtype(Py_TYPE(ob), (tp))) jpayne@69: jpayne@69: PyAPI_DATA(struct _typeobject) PyType_Type; /* built-in 'type' */ jpayne@69: PyAPI_DATA(struct _typeobject) PyBaseObject_Type; /* built-in 'object' */ jpayne@69: PyAPI_DATA(struct _typeobject) PySuper_Type; /* built-in 'super' */ jpayne@69: jpayne@69: PyAPI_FUNC(unsigned long) PyType_GetFlags(struct _typeobject*); jpayne@69: jpayne@69: #define PyType_Check(op) \ jpayne@69: PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS) jpayne@69: #define PyType_CheckExact(op) (Py_TYPE(op) == &PyType_Type) jpayne@69: jpayne@69: PyAPI_FUNC(int) PyType_Ready(struct _typeobject *); jpayne@69: PyAPI_FUNC(PyObject *) PyType_GenericAlloc(struct _typeobject *, Py_ssize_t); jpayne@69: PyAPI_FUNC(PyObject *) PyType_GenericNew(struct _typeobject *, jpayne@69: PyObject *, PyObject *); jpayne@69: PyAPI_FUNC(unsigned int) PyType_ClearCache(void); jpayne@69: PyAPI_FUNC(void) PyType_Modified(struct _typeobject *); jpayne@69: jpayne@69: /* Generic operations on objects */ jpayne@69: PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *); jpayne@69: PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *); jpayne@69: PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *); jpayne@69: PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *); jpayne@69: PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int); jpayne@69: PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int); jpayne@69: PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *); jpayne@69: PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *); jpayne@69: PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *); jpayne@69: PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *); jpayne@69: PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *); jpayne@69: PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *); jpayne@69: PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *); jpayne@69: PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *); jpayne@69: PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, jpayne@69: PyObject *, PyObject *); jpayne@69: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 jpayne@69: PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *); jpayne@69: #endif jpayne@69: PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *); jpayne@69: PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *); jpayne@69: PyAPI_FUNC(int) PyObject_IsTrue(PyObject *); jpayne@69: PyAPI_FUNC(int) PyObject_Not(PyObject *); jpayne@69: PyAPI_FUNC(int) PyCallable_Check(PyObject *); jpayne@69: PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *); jpayne@69: jpayne@69: /* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a jpayne@69: list of strings. PyObject_Dir(NULL) is like builtins.dir(), jpayne@69: returning the names of the current locals. In this case, if there are jpayne@69: no current locals, NULL is returned, and PyErr_Occurred() is false. jpayne@69: */ jpayne@69: PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *); jpayne@69: jpayne@69: jpayne@69: /* Helpers for printing recursive container types */ jpayne@69: PyAPI_FUNC(int) Py_ReprEnter(PyObject *); jpayne@69: PyAPI_FUNC(void) Py_ReprLeave(PyObject *); jpayne@69: jpayne@69: /* Flag bits for printing: */ jpayne@69: #define Py_PRINT_RAW 1 /* No string quotes etc. */ jpayne@69: jpayne@69: /* jpayne@69: Type flags (tp_flags) jpayne@69: jpayne@69: These flags are used to change expected features and behavior for a jpayne@69: particular type. jpayne@69: jpayne@69: Arbitration of the flag bit positions will need to be coordinated among jpayne@69: all extension writers who publicly release their extensions (this will jpayne@69: be fewer than you might expect!). jpayne@69: jpayne@69: Most flags were removed as of Python 3.0 to make room for new flags. (Some jpayne@69: flags are not for backwards compatibility but to indicate the presence of an jpayne@69: optional feature; these flags remain of course.) jpayne@69: jpayne@69: Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value. jpayne@69: jpayne@69: Code can use PyType_HasFeature(type_ob, flag_value) to test whether the jpayne@69: given type object has a specified feature. jpayne@69: */ jpayne@69: jpayne@69: /* Set if the type object is dynamically allocated */ jpayne@69: #define Py_TPFLAGS_HEAPTYPE (1UL << 9) jpayne@69: jpayne@69: /* Set if the type allows subclassing */ jpayne@69: #define Py_TPFLAGS_BASETYPE (1UL << 10) jpayne@69: jpayne@69: /* Set if the type implements the vectorcall protocol (PEP 590) */ jpayne@69: #ifndef Py_LIMITED_API jpayne@69: #define _Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11) jpayne@69: #endif jpayne@69: jpayne@69: /* Set if the type is 'ready' -- fully initialized */ jpayne@69: #define Py_TPFLAGS_READY (1UL << 12) jpayne@69: jpayne@69: /* Set while the type is being 'readied', to prevent recursive ready calls */ jpayne@69: #define Py_TPFLAGS_READYING (1UL << 13) jpayne@69: jpayne@69: /* Objects support garbage collection (see objimpl.h) */ jpayne@69: #define Py_TPFLAGS_HAVE_GC (1UL << 14) jpayne@69: jpayne@69: /* These two bits are preserved for Stackless Python, next after this is 17 */ jpayne@69: #ifdef STACKLESS jpayne@69: #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15) jpayne@69: #else jpayne@69: #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0 jpayne@69: #endif jpayne@69: jpayne@69: /* Objects behave like an unbound method */ jpayne@69: #define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17) jpayne@69: jpayne@69: /* Objects support type attribute cache */ jpayne@69: #define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18) jpayne@69: #define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19) jpayne@69: jpayne@69: /* Type is abstract and cannot be instantiated */ jpayne@69: #define Py_TPFLAGS_IS_ABSTRACT (1UL << 20) jpayne@69: jpayne@69: /* These flags are used to determine if a type is a subclass. */ jpayne@69: #define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24) jpayne@69: #define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25) jpayne@69: #define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26) jpayne@69: #define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27) jpayne@69: #define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28) jpayne@69: #define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29) jpayne@69: #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30) jpayne@69: #define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31) jpayne@69: jpayne@69: #define Py_TPFLAGS_DEFAULT ( \ jpayne@69: Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \ jpayne@69: Py_TPFLAGS_HAVE_VERSION_TAG | \ jpayne@69: 0) jpayne@69: jpayne@69: /* NOTE: The following flags reuse lower bits (removed as part of the jpayne@69: * Python 3.0 transition). */ jpayne@69: jpayne@69: /* The following flag is kept for compatibility. Starting with 3.8, jpayne@69: * binary compatibility of C extensions accross feature releases of jpayne@69: * Python is not supported anymore, except when using the stable ABI. jpayne@69: */ jpayne@69: jpayne@69: /* Type structure has tp_finalize member (3.4) */ jpayne@69: #define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0) jpayne@69: jpayne@69: #ifdef Py_LIMITED_API jpayne@69: # define PyType_HasFeature(t,f) ((PyType_GetFlags(t) & (f)) != 0) jpayne@69: #endif jpayne@69: #define PyType_FastSubclass(t,f) PyType_HasFeature(t,f) jpayne@69: jpayne@69: jpayne@69: /* jpayne@69: The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement jpayne@69: reference counts. Py_DECREF calls the object's deallocator function when jpayne@69: the refcount falls to 0; for jpayne@69: objects that don't contain references to other objects or heap memory jpayne@69: this can be the standard function free(). Both macros can be used jpayne@69: wherever a void expression is allowed. The argument must not be a jpayne@69: NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead. jpayne@69: The macro _Py_NewReference(op) initialize reference counts to 1, and jpayne@69: in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional jpayne@69: bookkeeping appropriate to the special build. jpayne@69: jpayne@69: We assume that the reference count field can never overflow; this can jpayne@69: be proven when the size of the field is the same as the pointer size, so jpayne@69: we ignore the possibility. Provided a C int is at least 32 bits (which jpayne@69: is implicitly assumed in many parts of this code), that's enough for jpayne@69: about 2**31 references to an object. jpayne@69: jpayne@69: XXX The following became out of date in Python 2.2, but I'm not sure jpayne@69: XXX what the full truth is now. Certainly, heap-allocated type objects jpayne@69: XXX can and should be deallocated. jpayne@69: Type objects should never be deallocated; the type pointer in an object jpayne@69: is not considered to be a reference to the type object, to save jpayne@69: complications in the deallocation function. (This is actually a jpayne@69: decision that's up to the implementer of each new type so if you want, jpayne@69: you can count such references to the type object.) jpayne@69: */ jpayne@69: jpayne@69: /* First define a pile of simple helper macros, one set per special jpayne@69: * build symbol. These either expand to the obvious things, or to jpayne@69: * nothing at all when the special mode isn't in effect. The main jpayne@69: * macros can later be defined just once then, yet expand to different jpayne@69: * things depending on which special build options are and aren't in effect. jpayne@69: * Trust me : while painful, this is 20x easier to understand than, jpayne@69: * e.g, defining _Py_NewReference five different times in a maze of nested jpayne@69: * #ifdefs (we used to do that -- it was impenetrable). jpayne@69: */ jpayne@69: #ifdef Py_REF_DEBUG jpayne@69: PyAPI_DATA(Py_ssize_t) _Py_RefTotal; jpayne@69: PyAPI_FUNC(void) _Py_NegativeRefcount(const char *filename, int lineno, jpayne@69: PyObject *op); jpayne@69: PyAPI_FUNC(Py_ssize_t) _Py_GetRefTotal(void); jpayne@69: #define _Py_INC_REFTOTAL _Py_RefTotal++ jpayne@69: #define _Py_DEC_REFTOTAL _Py_RefTotal-- jpayne@69: jpayne@69: /* Py_REF_DEBUG also controls the display of refcounts and memory block jpayne@69: * allocations at the interactive prompt and at interpreter shutdown jpayne@69: */ jpayne@69: PyAPI_FUNC(void) _PyDebug_PrintTotalRefs(void); jpayne@69: #else jpayne@69: #define _Py_INC_REFTOTAL jpayne@69: #define _Py_DEC_REFTOTAL jpayne@69: #endif /* Py_REF_DEBUG */ jpayne@69: jpayne@69: #ifdef COUNT_ALLOCS jpayne@69: PyAPI_FUNC(void) _Py_inc_count(struct _typeobject *); jpayne@69: PyAPI_FUNC(void) _Py_dec_count(struct _typeobject *); jpayne@69: #define _Py_INC_TPALLOCS(OP) _Py_inc_count(Py_TYPE(OP)) jpayne@69: #define _Py_INC_TPFREES(OP) _Py_dec_count(Py_TYPE(OP)) jpayne@69: #define _Py_DEC_TPFREES(OP) Py_TYPE(OP)->tp_frees-- jpayne@69: #define _Py_COUNT_ALLOCS_COMMA , jpayne@69: #else jpayne@69: #define _Py_INC_TPALLOCS(OP) jpayne@69: #define _Py_INC_TPFREES(OP) jpayne@69: #define _Py_DEC_TPFREES(OP) jpayne@69: #define _Py_COUNT_ALLOCS_COMMA jpayne@69: #endif /* COUNT_ALLOCS */ jpayne@69: jpayne@69: /* Update the Python traceback of an object. This function must be called jpayne@69: when a memory block is reused from a free list. */ jpayne@69: PyAPI_FUNC(int) _PyTraceMalloc_NewReference(PyObject *op); jpayne@69: jpayne@69: #ifdef Py_TRACE_REFS jpayne@69: /* Py_TRACE_REFS is such major surgery that we call external routines. */ jpayne@69: PyAPI_FUNC(void) _Py_NewReference(PyObject *); jpayne@69: PyAPI_FUNC(void) _Py_ForgetReference(PyObject *); jpayne@69: PyAPI_FUNC(void) _Py_PrintReferences(FILE *); jpayne@69: PyAPI_FUNC(void) _Py_PrintReferenceAddresses(FILE *); jpayne@69: PyAPI_FUNC(void) _Py_AddToAllObjects(PyObject *, int force); jpayne@69: #else jpayne@69: /* Without Py_TRACE_REFS, there's little enough to do that we expand code jpayne@69: inline. */ jpayne@69: static inline void _Py_NewReference(PyObject *op) jpayne@69: { jpayne@69: if (_Py_tracemalloc_config.tracing) { jpayne@69: _PyTraceMalloc_NewReference(op); jpayne@69: } jpayne@69: _Py_INC_TPALLOCS(op); jpayne@69: _Py_INC_REFTOTAL; jpayne@69: Py_REFCNT(op) = 1; jpayne@69: } jpayne@69: jpayne@69: static inline void _Py_ForgetReference(PyObject *op) jpayne@69: { jpayne@69: (void)op; /* may be unused, shut up -Wunused-parameter */ jpayne@69: _Py_INC_TPFREES(op); jpayne@69: } jpayne@69: #endif /* !Py_TRACE_REFS */ jpayne@69: jpayne@69: jpayne@69: PyAPI_FUNC(void) _Py_Dealloc(PyObject *); jpayne@69: jpayne@69: static inline void _Py_INCREF(PyObject *op) jpayne@69: { jpayne@69: _Py_INC_REFTOTAL; jpayne@69: op->ob_refcnt++; jpayne@69: } jpayne@69: jpayne@69: #define Py_INCREF(op) _Py_INCREF(_PyObject_CAST(op)) jpayne@69: jpayne@69: static inline void _Py_DECREF(const char *filename, int lineno, jpayne@69: PyObject *op) jpayne@69: { jpayne@69: (void)filename; /* may be unused, shut up -Wunused-parameter */ jpayne@69: (void)lineno; /* may be unused, shut up -Wunused-parameter */ jpayne@69: _Py_DEC_REFTOTAL; jpayne@69: if (--op->ob_refcnt != 0) { jpayne@69: #ifdef Py_REF_DEBUG jpayne@69: if (op->ob_refcnt < 0) { jpayne@69: _Py_NegativeRefcount(filename, lineno, op); jpayne@69: } jpayne@69: #endif jpayne@69: } jpayne@69: else { jpayne@69: _Py_Dealloc(op); jpayne@69: } jpayne@69: } jpayne@69: jpayne@69: #define Py_DECREF(op) _Py_DECREF(__FILE__, __LINE__, _PyObject_CAST(op)) jpayne@69: jpayne@69: jpayne@69: /* Safely decref `op` and set `op` to NULL, especially useful in tp_clear jpayne@69: * and tp_dealloc implementations. jpayne@69: * jpayne@69: * Note that "the obvious" code can be deadly: jpayne@69: * jpayne@69: * Py_XDECREF(op); jpayne@69: * op = NULL; jpayne@69: * jpayne@69: * Typically, `op` is something like self->containee, and `self` is done jpayne@69: * using its `containee` member. In the code sequence above, suppose jpayne@69: * `containee` is non-NULL with a refcount of 1. Its refcount falls to jpayne@69: * 0 on the first line, which can trigger an arbitrary amount of code, jpayne@69: * possibly including finalizers (like __del__ methods or weakref callbacks) jpayne@69: * coded in Python, which in turn can release the GIL and allow other threads jpayne@69: * to run, etc. Such code may even invoke methods of `self` again, or cause jpayne@69: * cyclic gc to trigger, but-- oops! --self->containee still points to the jpayne@69: * object being torn down, and it may be in an insane state while being torn jpayne@69: * down. This has in fact been a rich historic source of miserable (rare & jpayne@69: * hard-to-diagnose) segfaulting (and other) bugs. jpayne@69: * jpayne@69: * The safe way is: jpayne@69: * jpayne@69: * Py_CLEAR(op); jpayne@69: * jpayne@69: * That arranges to set `op` to NULL _before_ decref'ing, so that any code jpayne@69: * triggered as a side-effect of `op` getting torn down no longer believes jpayne@69: * `op` points to a valid object. jpayne@69: * jpayne@69: * There are cases where it's safe to use the naive code, but they're brittle. jpayne@69: * For example, if `op` points to a Python integer, you know that destroying jpayne@69: * one of those can't cause problems -- but in part that relies on that jpayne@69: * Python integers aren't currently weakly referencable. Best practice is jpayne@69: * to use Py_CLEAR() even if you can't think of a reason for why you need to. jpayne@69: */ jpayne@69: #define Py_CLEAR(op) \ jpayne@69: do { \ jpayne@69: PyObject *_py_tmp = _PyObject_CAST(op); \ jpayne@69: if (_py_tmp != NULL) { \ jpayne@69: (op) = NULL; \ jpayne@69: Py_DECREF(_py_tmp); \ jpayne@69: } \ jpayne@69: } while (0) jpayne@69: jpayne@69: /* Function to use in case the object pointer can be NULL: */ jpayne@69: static inline void _Py_XINCREF(PyObject *op) jpayne@69: { jpayne@69: if (op != NULL) { jpayne@69: Py_INCREF(op); jpayne@69: } jpayne@69: } jpayne@69: jpayne@69: #define Py_XINCREF(op) _Py_XINCREF(_PyObject_CAST(op)) jpayne@69: jpayne@69: static inline void _Py_XDECREF(PyObject *op) jpayne@69: { jpayne@69: if (op != NULL) { jpayne@69: Py_DECREF(op); jpayne@69: } jpayne@69: } jpayne@69: jpayne@69: #define Py_XDECREF(op) _Py_XDECREF(_PyObject_CAST(op)) jpayne@69: jpayne@69: /* jpayne@69: These are provided as conveniences to Python runtime embedders, so that jpayne@69: they can have object code that is not dependent on Python compilation flags. jpayne@69: */ jpayne@69: PyAPI_FUNC(void) Py_IncRef(PyObject *); jpayne@69: PyAPI_FUNC(void) Py_DecRef(PyObject *); jpayne@69: jpayne@69: /* jpayne@69: _Py_NoneStruct is an object of undefined type which can be used in contexts jpayne@69: where NULL (nil) is not suitable (since NULL often means 'error'). jpayne@69: jpayne@69: Don't forget to apply Py_INCREF() when returning this value!!! jpayne@69: */ jpayne@69: PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */ jpayne@69: #define Py_None (&_Py_NoneStruct) jpayne@69: jpayne@69: /* Macro for returning Py_None from a function */ jpayne@69: #define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None jpayne@69: jpayne@69: /* jpayne@69: Py_NotImplemented is a singleton used to signal that an operation is jpayne@69: not implemented for a given type combination. jpayne@69: */ jpayne@69: PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */ jpayne@69: #define Py_NotImplemented (&_Py_NotImplementedStruct) jpayne@69: jpayne@69: /* Macro for returning Py_NotImplemented from a function */ jpayne@69: #define Py_RETURN_NOTIMPLEMENTED \ jpayne@69: return Py_INCREF(Py_NotImplemented), Py_NotImplemented jpayne@69: jpayne@69: /* Rich comparison opcodes */ jpayne@69: #define Py_LT 0 jpayne@69: #define Py_LE 1 jpayne@69: #define Py_EQ 2 jpayne@69: #define Py_NE 3 jpayne@69: #define Py_GT 4 jpayne@69: #define Py_GE 5 jpayne@69: jpayne@69: /* jpayne@69: * Macro for implementing rich comparisons jpayne@69: * jpayne@69: * Needs to be a macro because any C-comparable type can be used. jpayne@69: */ jpayne@69: #define Py_RETURN_RICHCOMPARE(val1, val2, op) \ jpayne@69: do { \ jpayne@69: switch (op) { \ jpayne@69: case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ jpayne@69: case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ jpayne@69: case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ jpayne@69: case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ jpayne@69: case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ jpayne@69: case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \ jpayne@69: default: \ jpayne@69: Py_UNREACHABLE(); \ jpayne@69: } \ jpayne@69: } while (0) jpayne@69: jpayne@69: jpayne@69: /* jpayne@69: More conventions jpayne@69: ================ jpayne@69: jpayne@69: Argument Checking jpayne@69: ----------------- jpayne@69: jpayne@69: Functions that take objects as arguments normally don't check for nil jpayne@69: arguments, but they do check the type of the argument, and return an jpayne@69: error if the function doesn't apply to the type. jpayne@69: jpayne@69: Failure Modes jpayne@69: ------------- jpayne@69: jpayne@69: Functions may fail for a variety of reasons, including running out of jpayne@69: memory. This is communicated to the caller in two ways: an error string jpayne@69: is set (see errors.h), and the function result differs: functions that jpayne@69: normally return a pointer return NULL for failure, functions returning jpayne@69: an integer return -1 (which could be a legal return value too!), and jpayne@69: other functions return 0 for success and -1 for failure. jpayne@69: Callers should always check for errors before using the result. If jpayne@69: an error was set, the caller must either explicitly clear it, or pass jpayne@69: the error on to its caller. jpayne@69: jpayne@69: Reference Counts jpayne@69: ---------------- jpayne@69: jpayne@69: It takes a while to get used to the proper usage of reference counts. jpayne@69: jpayne@69: Functions that create an object set the reference count to 1; such new jpayne@69: objects must be stored somewhere or destroyed again with Py_DECREF(). jpayne@69: Some functions that 'store' objects, such as PyTuple_SetItem() and jpayne@69: PyList_SetItem(), jpayne@69: don't increment the reference count of the object, since the most jpayne@69: frequent use is to store a fresh object. Functions that 'retrieve' jpayne@69: objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also jpayne@69: don't increment jpayne@69: the reference count, since most frequently the object is only looked at jpayne@69: quickly. Thus, to retrieve an object and store it again, the caller jpayne@69: must call Py_INCREF() explicitly. jpayne@69: jpayne@69: NOTE: functions that 'consume' a reference count, like jpayne@69: PyList_SetItem(), consume the reference even if the object wasn't jpayne@69: successfully stored, to simplify error handling. jpayne@69: jpayne@69: It seems attractive to make other functions that take an object as jpayne@69: argument consume a reference count; however, this may quickly get jpayne@69: confusing (even the current practice is already confusing). Consider jpayne@69: it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at jpayne@69: times. jpayne@69: */ jpayne@69: jpayne@69: jpayne@69: /* Trashcan mechanism, thanks to Christian Tismer. jpayne@69: jpayne@69: When deallocating a container object, it's possible to trigger an unbounded jpayne@69: chain of deallocations, as each Py_DECREF in turn drops the refcount on "the jpayne@69: next" object in the chain to 0. This can easily lead to stack overflows, jpayne@69: especially in threads (which typically have less stack space to work with). jpayne@69: jpayne@69: A container object can avoid this by bracketing the body of its tp_dealloc jpayne@69: function with a pair of macros: jpayne@69: jpayne@69: static void jpayne@69: mytype_dealloc(mytype *p) jpayne@69: { jpayne@69: ... declarations go here ... jpayne@69: jpayne@69: PyObject_GC_UnTrack(p); // must untrack first jpayne@69: Py_TRASHCAN_BEGIN(p, mytype_dealloc) jpayne@69: ... The body of the deallocator goes here, including all calls ... jpayne@69: ... to Py_DECREF on contained objects. ... jpayne@69: Py_TRASHCAN_END // there should be no code after this jpayne@69: } jpayne@69: jpayne@69: CAUTION: Never return from the middle of the body! If the body needs to jpayne@69: "get out early", put a label immediately before the Py_TRASHCAN_END jpayne@69: call, and goto it. Else the call-depth counter (see below) will stay jpayne@69: above 0 forever, and the trashcan will never get emptied. jpayne@69: jpayne@69: How it works: The BEGIN macro increments a call-depth counter. So long jpayne@69: as this counter is small, the body of the deallocator is run directly without jpayne@69: further ado. But if the counter gets large, it instead adds p to a list of jpayne@69: objects to be deallocated later, skips the body of the deallocator, and jpayne@69: resumes execution after the END macro. The tp_dealloc routine then returns jpayne@69: without deallocating anything (and so unbounded call-stack depth is avoided). jpayne@69: jpayne@69: When the call stack finishes unwinding again, code generated by the END macro jpayne@69: notices this, and calls another routine to deallocate all the objects that jpayne@69: may have been added to the list of deferred deallocations. In effect, a jpayne@69: chain of N deallocations is broken into (N-1)/(PyTrash_UNWIND_LEVEL-1) pieces, jpayne@69: with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL. jpayne@69: jpayne@69: Since the tp_dealloc of a subclass typically calls the tp_dealloc of the base jpayne@69: class, we need to ensure that the trashcan is only triggered on the tp_dealloc jpayne@69: of the actual class being deallocated. Otherwise we might end up with a jpayne@69: partially-deallocated object. To check this, the tp_dealloc function must be jpayne@69: passed as second argument to Py_TRASHCAN_BEGIN(). jpayne@69: */ jpayne@69: jpayne@69: /* The new thread-safe private API, invoked by the macros below. */ jpayne@69: PyAPI_FUNC(void) _PyTrash_thread_deposit_object(PyObject*); jpayne@69: PyAPI_FUNC(void) _PyTrash_thread_destroy_chain(void); jpayne@69: jpayne@69: #define PyTrash_UNWIND_LEVEL 50 jpayne@69: jpayne@69: #define Py_TRASHCAN_BEGIN_CONDITION(op, cond) \ jpayne@69: do { \ jpayne@69: PyThreadState *_tstate = NULL; \ jpayne@69: /* If "cond" is false, then _tstate remains NULL and the deallocator \ jpayne@69: * is run normally without involving the trashcan */ \ jpayne@69: if (cond) { \ jpayne@69: _tstate = PyThreadState_GET(); \ jpayne@69: if (_tstate->trash_delete_nesting >= PyTrash_UNWIND_LEVEL) { \ jpayne@69: /* Store the object (to be deallocated later) and jump past \ jpayne@69: * Py_TRASHCAN_END, skipping the body of the deallocator */ \ jpayne@69: _PyTrash_thread_deposit_object(_PyObject_CAST(op)); \ jpayne@69: break; \ jpayne@69: } \ jpayne@69: ++_tstate->trash_delete_nesting; \ jpayne@69: } jpayne@69: /* The body of the deallocator is here. */ jpayne@69: #define Py_TRASHCAN_END \ jpayne@69: if (_tstate) { \ jpayne@69: --_tstate->trash_delete_nesting; \ jpayne@69: if (_tstate->trash_delete_later && _tstate->trash_delete_nesting <= 0) \ jpayne@69: _PyTrash_thread_destroy_chain(); \ jpayne@69: } \ jpayne@69: } while (0); jpayne@69: jpayne@69: #define Py_TRASHCAN_BEGIN(op, dealloc) Py_TRASHCAN_BEGIN_CONDITION(op, \ jpayne@69: Py_TYPE(op)->tp_dealloc == (destructor)(dealloc)) jpayne@69: jpayne@69: /* For backwards compatibility, these macros enable the trashcan jpayne@69: * unconditionally */ jpayne@69: #define Py_TRASHCAN_SAFE_BEGIN(op) Py_TRASHCAN_BEGIN_CONDITION(op, 1) jpayne@69: #define Py_TRASHCAN_SAFE_END(op) Py_TRASHCAN_END jpayne@69: jpayne@69: jpayne@69: #ifndef Py_LIMITED_API jpayne@69: # define Py_CPYTHON_OBJECT_H jpayne@69: # include "cpython/object.h" jpayne@69: # undef Py_CPYTHON_OBJECT_H jpayne@69: #endif jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: } jpayne@69: #endif jpayne@69: #endif /* !Py_OBJECT_H */