LCOV - code coverage report
Current view: top level - usr/include/python3.8 - object.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 7 7 100.0 %
Date: 2021-09-14 22:17:06 Functions: 1 1 100.0 %

          Line data    Source code
       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. */
     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             : 
     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             : 
     456             : static inline void _Py_INCREF(PyObject *op)
     457             : {
     458             :     _Py_INC_REFTOTAL;
     459         417 :     op->ob_refcnt++;
     460     1000007 : }
     461             : 
     462             : #define Py_INCREF(op) _Py_INCREF(_PyObject_CAST(op))
     463             : 
     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        2337 :     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        1239 :         _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: */
     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             : 
     538          24 : static inline void _Py_XDECREF(PyObject *op)
     539             : {
     540          24 :     if (op != NULL) {
     541             :         Py_DECREF(op);
     542             :     }
     543          24 : }
     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 */

Generated by: LCOV version 1.14