LCOV - code coverage report
Current view: top level - Include - object.h (source / functions) Hit Total Coverage
Test: CPython 3.12 LCOV report [commit 5e6661bce9] Lines: 48 49 98.0 %
Date: 2023-03-20 08:15:36 Functions: 17 17 100.0 %
Branches: 10 10 100.0 %

           Branch data     Line data    Source code
       1                 :            : #ifndef Py_OBJECT_H
       2                 :            : #define Py_OBJECT_H
       3                 :            : #ifdef __cplusplus
       4                 :            : extern "C" {
       5                 :            : #endif
       6                 :            : 
       7                 :            : 
       8                 :            : /* Object and type object interface */
       9                 :            : 
      10                 :            : /*
      11                 :            : Objects are structures allocated on the heap.  Special rules apply to
      12                 :            : the use of objects to ensure they are properly garbage-collected.
      13                 :            : Objects are never allocated statically or on the stack; they must be
      14                 :            : accessed through special macros and functions only.  (Type objects are
      15                 :            : exceptions to the first rule; the standard types are represented by
      16                 :            : statically initialized type objects, although work on type/class unification
      17                 :            : for Python 2.2 made it possible to have heap-allocated type objects too).
      18                 :            : 
      19                 :            : An object has a 'reference count' that is increased or decreased when a
      20                 :            : pointer to the object is copied or deleted; when the reference count
      21                 :            : reaches zero there are no references to the object left and it can be
      22                 :            : removed from the heap.
      23                 :            : 
      24                 :            : An object has a 'type' that determines what it represents and what kind
      25                 :            : of data it contains.  An object's type is fixed when it is created.
      26                 :            : Types themselves are represented as objects; an object contains a
      27                 :            : pointer to the corresponding type object.  The type itself has a type
      28                 :            : pointer pointing to the object representing the type 'type', which
      29                 :            : contains a pointer to itself!.
      30                 :            : 
      31                 :            : Objects do not float around in memory; once allocated an object keeps
      32                 :            : the same size and address.  Objects that must hold variable-size data
      33                 :            : can contain pointers to variable-size parts of the object.  Not all
      34                 :            : objects of the same type have the same size; but the size cannot change
      35                 :            : after allocation.  (These restrictions are made so a reference to an
      36                 :            : object can be simply a pointer -- moving an object would require
      37                 :            : updating all the pointers, and changing an object's size would require
      38                 :            : moving it if there was another object right next to it.)
      39                 :            : 
      40                 :            : Objects are always accessed through pointers of the type 'PyObject *'.
      41                 :            : The type 'PyObject' is a structure that only contains the reference count
      42                 :            : and the type pointer.  The actual memory allocated for an object
      43                 :            : contains other data that can only be accessed after casting the pointer
      44                 :            : to a pointer to a longer structure type.  This longer type must start
      45                 :            : with the reference count and type fields; the macro PyObject_HEAD should be
      46                 :            : used for this (to accommodate for future changes).  The implementation
      47                 :            : of a particular object type can cast the object pointer to the proper
      48                 :            : type and back.
      49                 :            : 
      50                 :            : A standard interface exists for objects that contain an array of items
      51                 :            : whose size is determined when the object is allocated.
      52                 :            : */
      53                 :            : 
      54                 :            : #include "pystats.h"
      55                 :            : 
      56                 :            : /* Py_DEBUG implies Py_REF_DEBUG. */
      57                 :            : #if defined(Py_DEBUG) && !defined(Py_REF_DEBUG)
      58                 :            : #  define Py_REF_DEBUG
      59                 :            : #endif
      60                 :            : 
      61                 :            : #if defined(Py_LIMITED_API) && defined(Py_TRACE_REFS)
      62                 :            : #  error Py_LIMITED_API is incompatible with Py_TRACE_REFS
      63                 :            : #endif
      64                 :            : 
      65                 :            : #ifdef Py_TRACE_REFS
      66                 :            : /* Define pointers to support a doubly-linked list of all live heap objects. */
      67                 :            : #define _PyObject_HEAD_EXTRA            \
      68                 :            :     PyObject *_ob_next;           \
      69                 :            :     PyObject *_ob_prev;
      70                 :            : 
      71                 :            : #define _PyObject_EXTRA_INIT _Py_NULL, _Py_NULL,
      72                 :            : 
      73                 :            : #else
      74                 :            : #  define _PyObject_HEAD_EXTRA
      75                 :            : #  define _PyObject_EXTRA_INIT
      76                 :            : #endif
      77                 :            : 
      78                 :            : /* PyObject_HEAD defines the initial segment of every PyObject. */
      79                 :            : #define PyObject_HEAD                   PyObject ob_base;
      80                 :            : 
      81                 :            : #define PyObject_HEAD_INIT(type)        \
      82                 :            :     { _PyObject_EXTRA_INIT              \
      83                 :            :     1, (type) },
      84                 :            : 
      85                 :            : #define PyVarObject_HEAD_INIT(type, size)       \
      86                 :            :     { PyObject_HEAD_INIT(type) (size) },
      87                 :            : 
      88                 :            : /* PyObject_VAR_HEAD defines the initial segment of all variable-size
      89                 :            :  * container objects.  These end with a declaration of an array with 1
      90                 :            :  * element, but enough space is malloc'ed so that the array actually
      91                 :            :  * has room for ob_size elements.  Note that ob_size is an element count,
      92                 :            :  * not necessarily a byte count.
      93                 :            :  */
      94                 :            : #define PyObject_VAR_HEAD      PyVarObject ob_base;
      95                 :            : #define Py_INVALID_SIZE (Py_ssize_t)-1
      96                 :            : 
      97                 :            : /* Nothing is actually declared to be a PyObject, but every pointer to
      98                 :            :  * a Python object can be cast to a PyObject*.  This is inheritance built
      99                 :            :  * by hand.  Similarly every pointer to a variable-size Python object can,
     100                 :            :  * in addition, be cast to PyVarObject*.
     101                 :            :  */
     102                 :            : struct _object {
     103                 :            :     _PyObject_HEAD_EXTRA
     104                 :            :     Py_ssize_t ob_refcnt;
     105                 :            :     PyTypeObject *ob_type;
     106                 :            : };
     107                 :            : 
     108                 :            : /* Cast argument to PyObject* type. */
     109                 :            : #define _PyObject_CAST(op) _Py_CAST(PyObject*, (op))
     110                 :            : 
     111                 :            : typedef struct {
     112                 :            :     PyObject ob_base;
     113                 :            :     Py_ssize_t ob_size; /* Number of items in variable part */
     114                 :            : } PyVarObject;
     115                 :            : 
     116                 :            : /* Cast argument to PyVarObject* type. */
     117                 :            : #define _PyVarObject_CAST(op) _Py_CAST(PyVarObject*, (op))
     118                 :            : 
     119                 :            : 
     120                 :            : // Test if the 'x' object is the 'y' object, the same as "x is y" in Python.
     121                 :            : PyAPI_FUNC(int) Py_Is(PyObject *x, PyObject *y);
     122                 :            : #define Py_Is(x, y) ((x) == (y))
     123                 :            : 
     124                 :            : 
     125                 :    8040154 : static inline Py_ssize_t Py_REFCNT(PyObject *ob) {
     126                 :    8040154 :     return ob->ob_refcnt;
     127                 :            : }
     128                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     129                 :            : #  define Py_REFCNT(ob) Py_REFCNT(_PyObject_CAST(ob))
     130                 :            : #endif
     131                 :            : 
     132                 :            : 
     133                 :            : // bpo-39573: The Py_SET_TYPE() function must be used to set an object type.
     134                 :  328836979 : static inline PyTypeObject* Py_TYPE(PyObject *ob) {
     135                 :  328836979 :     return ob->ob_type;
     136                 :            : }
     137                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     138                 :            : #  define Py_TYPE(ob) Py_TYPE(_PyObject_CAST(ob))
     139                 :            : #endif
     140                 :            : 
     141                 :            : // bpo-39573: The Py_SET_SIZE() function must be used to set an object size.
     142                 :  112896026 : static inline Py_ssize_t Py_SIZE(PyObject *ob) {
     143                 :  112896026 :     PyVarObject *var_ob = _PyVarObject_CAST(ob);
     144                 :  112896026 :     return var_ob->ob_size;
     145                 :            : }
     146                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     147                 :            : #  define Py_SIZE(ob) Py_SIZE(_PyObject_CAST(ob))
     148                 :            : #endif
     149                 :            : 
     150                 :            : 
     151                 :   67649253 : static inline int Py_IS_TYPE(PyObject *ob, PyTypeObject *type) {
     152                 :   67649253 :     return Py_TYPE(ob) == type;
     153                 :            : }
     154                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     155                 :            : #  define Py_IS_TYPE(ob, type) Py_IS_TYPE(_PyObject_CAST(ob), (type))
     156                 :            : #endif
     157                 :            : 
     158                 :            : 
     159                 :   31466638 : static inline void Py_SET_REFCNT(PyObject *ob, Py_ssize_t refcnt) {
     160                 :   31466638 :     ob->ob_refcnt = refcnt;
     161                 :   31466638 : }
     162                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     163                 :            : #  define Py_SET_REFCNT(ob, refcnt) Py_SET_REFCNT(_PyObject_CAST(ob), (refcnt))
     164                 :            : #endif
     165                 :            : 
     166                 :            : 
     167                 :   28346564 : static inline void Py_SET_TYPE(PyObject *ob, PyTypeObject *type) {
     168                 :   28346564 :     ob->ob_type = type;
     169                 :   28346564 : }
     170                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     171                 :            : #  define Py_SET_TYPE(ob, type) Py_SET_TYPE(_PyObject_CAST(ob), type)
     172                 :            : #endif
     173                 :            : 
     174                 :            : 
     175                 :   16923540 : static inline void Py_SET_SIZE(PyVarObject *ob, Py_ssize_t size) {
     176                 :   16923540 :     ob->ob_size = size;
     177                 :   16923540 : }
     178                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     179                 :            : #  define Py_SET_SIZE(ob, size) Py_SET_SIZE(_PyVarObject_CAST(ob), (size))
     180                 :            : #endif
     181                 :            : 
     182                 :            : 
     183                 :            : /*
     184                 :            : Type objects contain a string containing the type name (to help somewhat
     185                 :            : in debugging), the allocation parameters (see PyObject_New() and
     186                 :            : PyObject_NewVar()),
     187                 :            : and methods for accessing objects of the type.  Methods are optional, a
     188                 :            : nil pointer meaning that particular kind of access is not available for
     189                 :            : this type.  The Py_DECREF() macro uses the tp_dealloc method without
     190                 :            : checking for a nil pointer; it should always be implemented except if
     191                 :            : the implementation can guarantee that the reference count will never
     192                 :            : reach zero (e.g., for statically allocated type objects).
     193                 :            : 
     194                 :            : NB: the methods for certain type groups are now contained in separate
     195                 :            : method blocks.
     196                 :            : */
     197                 :            : 
     198                 :            : typedef PyObject * (*unaryfunc)(PyObject *);
     199                 :            : typedef PyObject * (*binaryfunc)(PyObject *, PyObject *);
     200                 :            : typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *);
     201                 :            : typedef int (*inquiry)(PyObject *);
     202                 :            : typedef Py_ssize_t (*lenfunc)(PyObject *);
     203                 :            : typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t);
     204                 :            : typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t);
     205                 :            : typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *);
     206                 :            : typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *);
     207                 :            : typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *);
     208                 :            : 
     209                 :            : typedef int (*objobjproc)(PyObject *, PyObject *);
     210                 :            : typedef int (*visitproc)(PyObject *, void *);
     211                 :            : typedef int (*traverseproc)(PyObject *, visitproc, void *);
     212                 :            : 
     213                 :            : 
     214                 :            : typedef void (*freefunc)(void *);
     215                 :            : typedef void (*destructor)(PyObject *);
     216                 :            : typedef PyObject *(*getattrfunc)(PyObject *, char *);
     217                 :            : typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
     218                 :            : typedef int (*setattrfunc)(PyObject *, char *, PyObject *);
     219                 :            : typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *);
     220                 :            : typedef PyObject *(*reprfunc)(PyObject *);
     221                 :            : typedef Py_hash_t (*hashfunc)(PyObject *);
     222                 :            : typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int);
     223                 :            : typedef PyObject *(*getiterfunc) (PyObject *);
     224                 :            : typedef PyObject *(*iternextfunc) (PyObject *);
     225                 :            : typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *);
     226                 :            : typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *);
     227                 :            : typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
     228                 :            : typedef PyObject *(*newfunc)(PyTypeObject *, PyObject *, PyObject *);
     229                 :            : typedef PyObject *(*allocfunc)(PyTypeObject *, Py_ssize_t);
     230                 :            : 
     231                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030c0000 // 3.12
     232                 :            : typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args,
     233                 :            :                                     size_t nargsf, PyObject *kwnames);
     234                 :            : #endif
     235                 :            : 
     236                 :            : typedef struct{
     237                 :            :     int slot;    /* slot id, see below */
     238                 :            :     void *pfunc; /* function pointer */
     239                 :            : } PyType_Slot;
     240                 :            : 
     241                 :            : typedef struct{
     242                 :            :     const char* name;
     243                 :            :     int basicsize;
     244                 :            :     int itemsize;
     245                 :            :     unsigned int flags;
     246                 :            :     PyType_Slot *slots; /* terminated by slot==0. */
     247                 :            : } PyType_Spec;
     248                 :            : 
     249                 :            : PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*);
     250                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
     251                 :            : PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*);
     252                 :            : #endif
     253                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000
     254                 :            : PyAPI_FUNC(void*) PyType_GetSlot(PyTypeObject*, int);
     255                 :            : #endif
     256                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000
     257                 :            : PyAPI_FUNC(PyObject*) PyType_FromModuleAndSpec(PyObject *, PyType_Spec *, PyObject *);
     258                 :            : PyAPI_FUNC(PyObject *) PyType_GetModule(PyTypeObject *);
     259                 :            : PyAPI_FUNC(void *) PyType_GetModuleState(PyTypeObject *);
     260                 :            : #endif
     261                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030B0000
     262                 :            : PyAPI_FUNC(PyObject *) PyType_GetName(PyTypeObject *);
     263                 :            : PyAPI_FUNC(PyObject *) PyType_GetQualName(PyTypeObject *);
     264                 :            : #endif
     265                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
     266                 :            : PyAPI_FUNC(PyObject *) PyType_FromMetaclass(PyTypeObject*, PyObject*, PyType_Spec*, PyObject*);
     267                 :            : #endif
     268                 :            : 
     269                 :            : /* Generic type check */
     270                 :            : PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *);
     271                 :            : 
     272                 :    7876598 : static inline int PyObject_TypeCheck(PyObject *ob, PyTypeObject *type) {
     273   [ +  +  +  + ]:    7876598 :     return Py_IS_TYPE(ob, type) || PyType_IsSubtype(Py_TYPE(ob), type);
     274                 :            : }
     275                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     276                 :            : #  define PyObject_TypeCheck(ob, type) PyObject_TypeCheck(_PyObject_CAST(ob), (type))
     277                 :            : #endif
     278                 :            : 
     279                 :            : PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */
     280                 :            : PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */
     281                 :            : PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */
     282                 :            : 
     283                 :            : PyAPI_FUNC(unsigned long) PyType_GetFlags(PyTypeObject*);
     284                 :            : 
     285                 :            : PyAPI_FUNC(int) PyType_Ready(PyTypeObject *);
     286                 :            : PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t);
     287                 :            : PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *,
     288                 :            :                                                PyObject *, PyObject *);
     289                 :            : PyAPI_FUNC(unsigned int) PyType_ClearCache(void);
     290                 :            : PyAPI_FUNC(void) PyType_Modified(PyTypeObject *);
     291                 :            : 
     292                 :            : /* Generic operations on objects */
     293                 :            : PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
     294                 :            : PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
     295                 :            : PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *);
     296                 :            : PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *);
     297                 :            : PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
     298                 :            : PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
     299                 :            : PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *);
     300                 :            : PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *);
     301                 :            : PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *);
     302                 :            : PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
     303                 :            : PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
     304                 :            : PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
     305                 :            : PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *);
     306                 :            : PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
     307                 :            : PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, PyObject *, PyObject *);
     308                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
     309                 :            : PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *);
     310                 :            : #endif
     311                 :            : PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *);
     312                 :            : PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *);
     313                 :            : PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
     314                 :            : PyAPI_FUNC(int) PyObject_Not(PyObject *);
     315                 :            : PyAPI_FUNC(int) PyCallable_Check(PyObject *);
     316                 :            : PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
     317                 :            : 
     318                 :            : /* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a
     319                 :            :    list of strings.  PyObject_Dir(NULL) is like builtins.dir(),
     320                 :            :    returning the names of the current locals.  In this case, if there are
     321                 :            :    no current locals, NULL is returned, and PyErr_Occurred() is false.
     322                 :            : */
     323                 :            : PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
     324                 :            : 
     325                 :            : /* Pickle support. */
     326                 :            : #ifndef Py_LIMITED_API
     327                 :            : PyAPI_FUNC(PyObject *) _PyObject_GetState(PyObject *);
     328                 :            : #endif
     329                 :            : 
     330                 :            : 
     331                 :            : /* Helpers for printing recursive container types */
     332                 :            : PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
     333                 :            : PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
     334                 :            : 
     335                 :            : /* Flag bits for printing: */
     336                 :            : #define Py_PRINT_RAW    1       /* No string quotes etc. */
     337                 :            : 
     338                 :            : /*
     339                 :            : Type flags (tp_flags)
     340                 :            : 
     341                 :            : These flags are used to change expected features and behavior for a
     342                 :            : particular type.
     343                 :            : 
     344                 :            : Arbitration of the flag bit positions will need to be coordinated among
     345                 :            : all extension writers who publicly release their extensions (this will
     346                 :            : be fewer than you might expect!).
     347                 :            : 
     348                 :            : Most flags were removed as of Python 3.0 to make room for new flags.  (Some
     349                 :            : flags are not for backwards compatibility but to indicate the presence of an
     350                 :            : optional feature; these flags remain of course.)
     351                 :            : 
     352                 :            : Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
     353                 :            : 
     354                 :            : Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
     355                 :            : given type object has a specified feature.
     356                 :            : */
     357                 :            : 
     358                 :            : #ifndef Py_LIMITED_API
     359                 :            : 
     360                 :            : /* Track types initialized using _PyStaticType_InitBuiltin(). */
     361                 :            : #define _Py_TPFLAGS_STATIC_BUILTIN (1 << 1)
     362                 :            : 
     363                 :            : /* Placement of weakref pointers are managed by the VM, not by the type.
     364                 :            :  * The VM will automatically set tp_weaklistoffset.
     365                 :            :  */
     366                 :            : #define Py_TPFLAGS_MANAGED_WEAKREF (1 << 3)
     367                 :            : 
     368                 :            : /* Placement of dict (and values) pointers are managed by the VM, not by the type.
     369                 :            :  * The VM will automatically set tp_dictoffset.
     370                 :            :  */
     371                 :            : #define Py_TPFLAGS_MANAGED_DICT (1 << 4)
     372                 :            : 
     373                 :            : #define Py_TPFLAGS_PREHEADER (Py_TPFLAGS_MANAGED_WEAKREF | Py_TPFLAGS_MANAGED_DICT)
     374                 :            : 
     375                 :            : /* Set if instances of the type object are treated as sequences for pattern matching */
     376                 :            : #define Py_TPFLAGS_SEQUENCE (1 << 5)
     377                 :            : /* Set if instances of the type object are treated as mappings for pattern matching */
     378                 :            : #define Py_TPFLAGS_MAPPING (1 << 6)
     379                 :            : #endif
     380                 :            : 
     381                 :            : /* Disallow creating instances of the type: set tp_new to NULL and don't create
     382                 :            :  * the "__new__" key in the type dictionary. */
     383                 :            : #define Py_TPFLAGS_DISALLOW_INSTANTIATION (1UL << 7)
     384                 :            : 
     385                 :            : /* Set if the type object is immutable: type attributes cannot be set nor deleted */
     386                 :            : #define Py_TPFLAGS_IMMUTABLETYPE (1UL << 8)
     387                 :            : 
     388                 :            : /* Set if the type object is dynamically allocated */
     389                 :            : #define Py_TPFLAGS_HEAPTYPE (1UL << 9)
     390                 :            : 
     391                 :            : /* Set if the type allows subclassing */
     392                 :            : #define Py_TPFLAGS_BASETYPE (1UL << 10)
     393                 :            : 
     394                 :            : /* Set if the type implements the vectorcall protocol (PEP 590) */
     395                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
     396                 :            : #define Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11)
     397                 :            : #ifndef Py_LIMITED_API
     398                 :            : // Backwards compatibility alias for API that was provisional in Python 3.8
     399                 :            : #define _Py_TPFLAGS_HAVE_VECTORCALL Py_TPFLAGS_HAVE_VECTORCALL
     400                 :            : #endif
     401                 :            : #endif
     402                 :            : 
     403                 :            : /* Set if the type is 'ready' -- fully initialized */
     404                 :            : #define Py_TPFLAGS_READY (1UL << 12)
     405                 :            : 
     406                 :            : /* Set while the type is being 'readied', to prevent recursive ready calls */
     407                 :            : #define Py_TPFLAGS_READYING (1UL << 13)
     408                 :            : 
     409                 :            : /* Objects support garbage collection (see objimpl.h) */
     410                 :            : #define Py_TPFLAGS_HAVE_GC (1UL << 14)
     411                 :            : 
     412                 :            : /* These two bits are preserved for Stackless Python, next after this is 17 */
     413                 :            : #ifdef STACKLESS
     414                 :            : #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15)
     415                 :            : #else
     416                 :            : #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
     417                 :            : #endif
     418                 :            : 
     419                 :            : /* Objects behave like an unbound method */
     420                 :            : #define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17)
     421                 :            : 
     422                 :            : /* Object has up-to-date type attribute cache */
     423                 :            : #define Py_TPFLAGS_VALID_VERSION_TAG  (1UL << 19)
     424                 :            : 
     425                 :            : /* Type is abstract and cannot be instantiated */
     426                 :            : #define Py_TPFLAGS_IS_ABSTRACT (1UL << 20)
     427                 :            : 
     428                 :            : // This undocumented flag gives certain built-ins their unique pattern-matching
     429                 :            : // behavior, which allows a single positional subpattern to match against the
     430                 :            : // subject itself (rather than a mapped attribute on it):
     431                 :            : #define _Py_TPFLAGS_MATCH_SELF (1UL << 22)
     432                 :            : 
     433                 :            : /* These flags are used to determine if a type is a subclass. */
     434                 :            : #define Py_TPFLAGS_LONG_SUBCLASS        (1UL << 24)
     435                 :            : #define Py_TPFLAGS_LIST_SUBCLASS        (1UL << 25)
     436                 :            : #define Py_TPFLAGS_TUPLE_SUBCLASS       (1UL << 26)
     437                 :            : #define Py_TPFLAGS_BYTES_SUBCLASS       (1UL << 27)
     438                 :            : #define Py_TPFLAGS_UNICODE_SUBCLASS     (1UL << 28)
     439                 :            : #define Py_TPFLAGS_DICT_SUBCLASS        (1UL << 29)
     440                 :            : #define Py_TPFLAGS_BASE_EXC_SUBCLASS    (1UL << 30)
     441                 :            : #define Py_TPFLAGS_TYPE_SUBCLASS        (1UL << 31)
     442                 :            : 
     443                 :            : #define Py_TPFLAGS_DEFAULT  ( \
     444                 :            :                  Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
     445                 :            :                 0)
     446                 :            : 
     447                 :            : /* NOTE: Some of the following flags reuse lower bits (removed as part of the
     448                 :            :  * Python 3.0 transition). */
     449                 :            : 
     450                 :            : /* The following flags are kept for compatibility; in previous
     451                 :            :  * versions they indicated presence of newer tp_* fields on the
     452                 :            :  * type struct.
     453                 :            :  * Starting with 3.8, binary compatibility of C extensions across
     454                 :            :  * feature releases of Python is not supported anymore (except when
     455                 :            :  * using the stable ABI, in which all classes are created dynamically,
     456                 :            :  * using the interpreter's memory layout.)
     457                 :            :  * Note that older extensions using the stable ABI set these flags,
     458                 :            :  * so the bits must not be repurposed.
     459                 :            :  */
     460                 :            : #define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0)
     461                 :            : #define Py_TPFLAGS_HAVE_VERSION_TAG   (1UL << 18)
     462                 :            : 
     463                 :            : 
     464                 :            : /*
     465                 :            : The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
     466                 :            : reference counts.  Py_DECREF calls the object's deallocator function when
     467                 :            : the refcount falls to 0; for
     468                 :            : objects that don't contain references to other objects or heap memory
     469                 :            : this can be the standard function free().  Both macros can be used
     470                 :            : wherever a void expression is allowed.  The argument must not be a
     471                 :            : NULL pointer.  If it may be NULL, use Py_XINCREF/Py_XDECREF instead.
     472                 :            : The macro _Py_NewReference(op) initialize reference counts to 1, and
     473                 :            : in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
     474                 :            : bookkeeping appropriate to the special build.
     475                 :            : 
     476                 :            : We assume that the reference count field can never overflow; this can
     477                 :            : be proven when the size of the field is the same as the pointer size, so
     478                 :            : we ignore the possibility.  Provided a C int is at least 32 bits (which
     479                 :            : is implicitly assumed in many parts of this code), that's enough for
     480                 :            : about 2**31 references to an object.
     481                 :            : 
     482                 :            : XXX The following became out of date in Python 2.2, but I'm not sure
     483                 :            : XXX what the full truth is now.  Certainly, heap-allocated type objects
     484                 :            : XXX can and should be deallocated.
     485                 :            : Type objects should never be deallocated; the type pointer in an object
     486                 :            : is not considered to be a reference to the type object, to save
     487                 :            : complications in the deallocation function.  (This is actually a
     488                 :            : decision that's up to the implementer of each new type so if you want,
     489                 :            : you can count such references to the type object.)
     490                 :            : */
     491                 :            : 
     492                 :            : #ifdef Py_REF_DEBUG
     493                 :            : #  if defined(Py_LIMITED_API) && Py_LIMITED_API+0 < 0x030A0000
     494                 :            : extern Py_ssize_t _Py_RefTotal;
     495                 :            : #    define _Py_INC_REFTOTAL() _Py_RefTotal++
     496                 :            : #    define _Py_DEC_REFTOTAL() _Py_RefTotal--
     497                 :            : #  elif defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
     498                 :            : extern void _Py_IncRefTotal(void);
     499                 :            : extern void _Py_DecRefTotal(void);
     500                 :            : #    define _Py_INC_REFTOTAL() _Py_IncRefTotal()
     501                 :            : #    define _Py_DEC_REFTOTAL() _Py_DecRefTotal()
     502                 :            : #  elif !defined(Py_LIMITED_API) || Py_LIMITED_API+0 > 0x030C0000
     503                 :            : extern void _Py_IncRefTotal_DO_NOT_USE_THIS(void);
     504                 :            : extern void _Py_DecRefTotal_DO_NOT_USE_THIS(void);
     505                 :            : #    define _Py_INC_REFTOTAL() _Py_IncRefTotal_DO_NOT_USE_THIS()
     506                 :            : #    define _Py_DEC_REFTOTAL() _Py_DecRefTotal_DO_NOT_USE_THIS()
     507                 :            : #  endif
     508                 :            : PyAPI_FUNC(void) _Py_NegativeRefcount(const char *filename, int lineno,
     509                 :            :                                       PyObject *op);
     510                 :            : #endif /* Py_REF_DEBUG */
     511                 :            : 
     512                 :            : PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
     513                 :            : 
     514                 :            : /*
     515                 :            : These are provided as conveniences to Python runtime embedders, so that
     516                 :            : they can have object code that is not dependent on Python compilation flags.
     517                 :            : */
     518                 :            : PyAPI_FUNC(void) Py_IncRef(PyObject *);
     519                 :            : PyAPI_FUNC(void) Py_DecRef(PyObject *);
     520                 :            : 
     521                 :            : // Similar to Py_IncRef() and Py_DecRef() but the argument must be non-NULL.
     522                 :            : // Private functions used by Py_INCREF() and Py_DECREF().
     523                 :            : PyAPI_FUNC(void) _Py_IncRef(PyObject *);
     524                 :            : PyAPI_FUNC(void) _Py_DecRef(PyObject *);
     525                 :            : 
     526                 :  161420248 : static inline void Py_INCREF(PyObject *op)
     527                 :            : {
     528                 :            : #if defined(Py_REF_DEBUG) && defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030A0000
     529                 :            :     // Stable ABI for Python 3.10 built in debug mode.
     530                 :            :     _Py_IncRef(op);
     531                 :            : #else
     532                 :            :     _Py_INCREF_STAT_INC();
     533                 :            :     // Non-limited C API and limited C API for Python 3.9 and older access
     534                 :            :     // directly PyObject.ob_refcnt.
     535                 :            : #ifdef Py_REF_DEBUG
     536                 :            :     _Py_INC_REFTOTAL();
     537                 :            : #endif  // Py_REF_DEBUG
     538                 :  161420248 :     op->ob_refcnt++;
     539                 :            : #endif
     540                 :  161420248 : }
     541                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     542                 :            : #  define Py_INCREF(op) Py_INCREF(_PyObject_CAST(op))
     543                 :            : #endif
     544                 :            : 
     545                 :            : #if defined(Py_REF_DEBUG) && defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030A0000
     546                 :            : // Stable ABI for limited C API version 3.10 of Python debug build
     547                 :            : static inline void Py_DECREF(PyObject *op) {
     548                 :            :     _Py_DecRef(op);
     549                 :            : }
     550                 :            : #define Py_DECREF(op) Py_DECREF(_PyObject_CAST(op))
     551                 :            : 
     552                 :            : #elif defined(Py_REF_DEBUG)
     553                 :            : static inline void Py_DECREF(const char *filename, int lineno, PyObject *op)
     554                 :            : {
     555                 :            :     _Py_DECREF_STAT_INC();
     556                 :            :     _Py_DEC_REFTOTAL();
     557                 :            :     if (--op->ob_refcnt != 0) {
     558                 :            :         if (op->ob_refcnt < 0) {
     559                 :            :             _Py_NegativeRefcount(filename, lineno, op);
     560                 :            :         }
     561                 :            :     }
     562                 :            :     else {
     563                 :            :         _Py_Dealloc(op);
     564                 :            :     }
     565                 :            : }
     566                 :            : #define Py_DECREF(op) Py_DECREF(__FILE__, __LINE__, _PyObject_CAST(op))
     567                 :            : 
     568                 :            : #else
     569                 :  112122299 : static inline void Py_DECREF(PyObject *op)
     570                 :            : {
     571                 :            :     _Py_DECREF_STAT_INC();
     572                 :            :     // Non-limited C API and limited C API for Python 3.9 and older access
     573                 :            :     // directly PyObject.ob_refcnt.
     574         [ +  + ]:  112122299 :     if (--op->ob_refcnt == 0) {
     575                 :   18024377 :         _Py_Dealloc(op);
     576                 :            :     }
     577                 :  112122299 : }
     578                 :            : #define Py_DECREF(op) Py_DECREF(_PyObject_CAST(op))
     579                 :            : #endif
     580                 :            : 
     581                 :            : #undef _Py_INC_REFTOTAL
     582                 :            : #undef _Py_DEC_REFTOTAL
     583                 :            : 
     584                 :            : 
     585                 :            : /* Safely decref `op` and set `op` to NULL, especially useful in tp_clear
     586                 :            :  * and tp_dealloc implementations.
     587                 :            :  *
     588                 :            :  * Note that "the obvious" code can be deadly:
     589                 :            :  *
     590                 :            :  *     Py_XDECREF(op);
     591                 :            :  *     op = NULL;
     592                 :            :  *
     593                 :            :  * Typically, `op` is something like self->containee, and `self` is done
     594                 :            :  * using its `containee` member.  In the code sequence above, suppose
     595                 :            :  * `containee` is non-NULL with a refcount of 1.  Its refcount falls to
     596                 :            :  * 0 on the first line, which can trigger an arbitrary amount of code,
     597                 :            :  * possibly including finalizers (like __del__ methods or weakref callbacks)
     598                 :            :  * coded in Python, which in turn can release the GIL and allow other threads
     599                 :            :  * to run, etc.  Such code may even invoke methods of `self` again, or cause
     600                 :            :  * cyclic gc to trigger, but-- oops! --self->containee still points to the
     601                 :            :  * object being torn down, and it may be in an insane state while being torn
     602                 :            :  * down.  This has in fact been a rich historic source of miserable (rare &
     603                 :            :  * hard-to-diagnose) segfaulting (and other) bugs.
     604                 :            :  *
     605                 :            :  * The safe way is:
     606                 :            :  *
     607                 :            :  *      Py_CLEAR(op);
     608                 :            :  *
     609                 :            :  * That arranges to set `op` to NULL _before_ decref'ing, so that any code
     610                 :            :  * triggered as a side-effect of `op` getting torn down no longer believes
     611                 :            :  * `op` points to a valid object.
     612                 :            :  *
     613                 :            :  * There are cases where it's safe to use the naive code, but they're brittle.
     614                 :            :  * For example, if `op` points to a Python integer, you know that destroying
     615                 :            :  * one of those can't cause problems -- but in part that relies on that
     616                 :            :  * Python integers aren't currently weakly referencable.  Best practice is
     617                 :            :  * to use Py_CLEAR() even if you can't think of a reason for why you need to.
     618                 :            :  *
     619                 :            :  * gh-98724: Use a temporary variable to only evaluate the macro argument once,
     620                 :            :  * to avoid the duplication of side effects if the argument has side effects.
     621                 :            :  *
     622                 :            :  * gh-99701: If the PyObject* type is used with casting arguments to PyObject*,
     623                 :            :  * the code can be miscompiled with strict aliasing because of type punning.
     624                 :            :  * With strict aliasing, a compiler considers that two pointers of different
     625                 :            :  * types cannot read or write the same memory which enables optimization
     626                 :            :  * opportunities.
     627                 :            :  *
     628                 :            :  * If available, use _Py_TYPEOF() to use the 'op' type for temporary variables,
     629                 :            :  * and so avoid type punning. Otherwise, use memcpy() which causes type erasure
     630                 :            :  * and so prevents the compiler to reuse an old cached 'op' value after
     631                 :            :  * Py_CLEAR().
     632                 :            :  */
     633                 :            : #ifdef _Py_TYPEOF
     634                 :            : #define Py_CLEAR(op) \
     635                 :            :     do { \
     636                 :            :         _Py_TYPEOF(op)* _tmp_op_ptr = &(op); \
     637                 :            :         _Py_TYPEOF(op) _tmp_old_op = (*_tmp_op_ptr); \
     638                 :            :         if (_tmp_old_op != NULL) { \
     639                 :            :             *_tmp_op_ptr = _Py_NULL; \
     640                 :            :             Py_DECREF(_tmp_old_op); \
     641                 :            :         } \
     642                 :            :     } while (0)
     643                 :            : #else
     644                 :            : #define Py_CLEAR(op) \
     645                 :            :     do { \
     646                 :            :         PyObject **_tmp_op_ptr = _Py_CAST(PyObject**, &(op)); \
     647                 :            :         PyObject *_tmp_old_op = (*_tmp_op_ptr); \
     648                 :            :         if (_tmp_old_op != NULL) { \
     649                 :            :             PyObject *_null_ptr = _Py_NULL; \
     650                 :            :             memcpy(_tmp_op_ptr, &_null_ptr, sizeof(PyObject*)); \
     651                 :            :             Py_DECREF(_tmp_old_op); \
     652                 :            :         } \
     653                 :            :     } while (0)
     654                 :            : #endif
     655                 :            : 
     656                 :            : 
     657                 :            : /* Function to use in case the object pointer can be NULL: */
     658                 :    7162978 : static inline void Py_XINCREF(PyObject *op)
     659                 :            : {
     660         [ +  + ]:    7162978 :     if (op != _Py_NULL) {
     661                 :    2901381 :         Py_INCREF(op);
     662                 :            :     }
     663                 :    7162978 : }
     664                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     665                 :            : #  define Py_XINCREF(op) Py_XINCREF(_PyObject_CAST(op))
     666                 :            : #endif
     667                 :            : 
     668                 :   72166708 : static inline void Py_XDECREF(PyObject *op)
     669                 :            : {
     670         [ +  + ]:   72166708 :     if (op != _Py_NULL) {
     671                 :   49898426 :         Py_DECREF(op);
     672                 :            :     }
     673                 :   72166708 : }
     674                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     675                 :            : #  define Py_XDECREF(op) Py_XDECREF(_PyObject_CAST(op))
     676                 :            : #endif
     677                 :            : 
     678                 :            : // Create a new strong reference to an object:
     679                 :            : // increment the reference count of the object and return the object.
     680                 :            : PyAPI_FUNC(PyObject*) Py_NewRef(PyObject *obj);
     681                 :            : 
     682                 :            : // Similar to Py_NewRef(), but the object can be NULL.
     683                 :            : PyAPI_FUNC(PyObject*) Py_XNewRef(PyObject *obj);
     684                 :            : 
     685                 :   68133682 : static inline PyObject* _Py_NewRef(PyObject *obj)
     686                 :            : {
     687                 :   68133682 :     Py_INCREF(obj);
     688                 :   68133682 :     return obj;
     689                 :            : }
     690                 :            : 
     691                 :    5696057 : static inline PyObject* _Py_XNewRef(PyObject *obj)
     692                 :            : {
     693                 :    5696057 :     Py_XINCREF(obj);
     694                 :    5696057 :     return obj;
     695                 :            : }
     696                 :            : 
     697                 :            : // Py_NewRef() and Py_XNewRef() are exported as functions for the stable ABI.
     698                 :            : // Names overridden with macros by static inline functions for best
     699                 :            : // performances.
     700                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     701                 :            : #  define Py_NewRef(obj) _Py_NewRef(_PyObject_CAST(obj))
     702                 :            : #  define Py_XNewRef(obj) _Py_XNewRef(_PyObject_CAST(obj))
     703                 :            : #else
     704                 :            : #  define Py_NewRef(obj) _Py_NewRef(obj)
     705                 :            : #  define Py_XNewRef(obj) _Py_XNewRef(obj)
     706                 :            : #endif
     707                 :            : 
     708                 :            : 
     709                 :            : /*
     710                 :            : _Py_NoneStruct is an object of undefined type which can be used in contexts
     711                 :            : where NULL (nil) is not suitable (since NULL often means 'error').
     712                 :            : 
     713                 :            : Don't forget to apply Py_INCREF() when returning this value!!!
     714                 :            : */
     715                 :            : PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
     716                 :            : #define Py_None (&_Py_NoneStruct)
     717                 :            : 
     718                 :            : // Test if an object is the None singleton, the same as "x is None" in Python.
     719                 :            : PyAPI_FUNC(int) Py_IsNone(PyObject *x);
     720                 :            : #define Py_IsNone(x) Py_Is((x), Py_None)
     721                 :            : 
     722                 :            : /* Macro for returning Py_None from a function */
     723                 :            : #define Py_RETURN_NONE return Py_NewRef(Py_None)
     724                 :            : 
     725                 :            : /*
     726                 :            : Py_NotImplemented is a singleton used to signal that an operation is
     727                 :            : not implemented for a given type combination.
     728                 :            : */
     729                 :            : PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
     730                 :            : #define Py_NotImplemented (&_Py_NotImplementedStruct)
     731                 :            : 
     732                 :            : /* Macro for returning Py_NotImplemented from a function */
     733                 :            : #define Py_RETURN_NOTIMPLEMENTED return Py_NewRef(Py_NotImplemented)
     734                 :            : 
     735                 :            : /* Rich comparison opcodes */
     736                 :            : #define Py_LT 0
     737                 :            : #define Py_LE 1
     738                 :            : #define Py_EQ 2
     739                 :            : #define Py_NE 3
     740                 :            : #define Py_GT 4
     741                 :            : #define Py_GE 5
     742                 :            : 
     743                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000
     744                 :            : /* Result of calling PyIter_Send */
     745                 :            : typedef enum {
     746                 :            :     PYGEN_RETURN = 0,
     747                 :            :     PYGEN_ERROR = -1,
     748                 :            :     PYGEN_NEXT = 1,
     749                 :            : } PySendResult;
     750                 :            : #endif
     751                 :            : 
     752                 :            : /*
     753                 :            :  * Macro for implementing rich comparisons
     754                 :            :  *
     755                 :            :  * Needs to be a macro because any C-comparable type can be used.
     756                 :            :  */
     757                 :            : #define Py_RETURN_RICHCOMPARE(val1, val2, op)                               \
     758                 :            :     do {                                                                    \
     759                 :            :         switch (op) {                                                       \
     760                 :            :         case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE;  \
     761                 :            :         case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE;  \
     762                 :            :         case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE;   \
     763                 :            :         case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE;   \
     764                 :            :         case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE;  \
     765                 :            :         case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE;  \
     766                 :            :         default:                                                            \
     767                 :            :             Py_UNREACHABLE();                                               \
     768                 :            :         }                                                                   \
     769                 :            :     } while (0)
     770                 :            : 
     771                 :            : 
     772                 :            : /*
     773                 :            : More conventions
     774                 :            : ================
     775                 :            : 
     776                 :            : Argument Checking
     777                 :            : -----------------
     778                 :            : 
     779                 :            : Functions that take objects as arguments normally don't check for nil
     780                 :            : arguments, but they do check the type of the argument, and return an
     781                 :            : error if the function doesn't apply to the type.
     782                 :            : 
     783                 :            : Failure Modes
     784                 :            : -------------
     785                 :            : 
     786                 :            : Functions may fail for a variety of reasons, including running out of
     787                 :            : memory.  This is communicated to the caller in two ways: an error string
     788                 :            : is set (see errors.h), and the function result differs: functions that
     789                 :            : normally return a pointer return NULL for failure, functions returning
     790                 :            : an integer return -1 (which could be a legal return value too!), and
     791                 :            : other functions return 0 for success and -1 for failure.
     792                 :            : Callers should always check for errors before using the result.  If
     793                 :            : an error was set, the caller must either explicitly clear it, or pass
     794                 :            : the error on to its caller.
     795                 :            : 
     796                 :            : Reference Counts
     797                 :            : ----------------
     798                 :            : 
     799                 :            : It takes a while to get used to the proper usage of reference counts.
     800                 :            : 
     801                 :            : Functions that create an object set the reference count to 1; such new
     802                 :            : objects must be stored somewhere or destroyed again with Py_DECREF().
     803                 :            : Some functions that 'store' objects, such as PyTuple_SetItem() and
     804                 :            : PyList_SetItem(),
     805                 :            : don't increment the reference count of the object, since the most
     806                 :            : frequent use is to store a fresh object.  Functions that 'retrieve'
     807                 :            : objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
     808                 :            : don't increment
     809                 :            : the reference count, since most frequently the object is only looked at
     810                 :            : quickly.  Thus, to retrieve an object and store it again, the caller
     811                 :            : must call Py_INCREF() explicitly.
     812                 :            : 
     813                 :            : NOTE: functions that 'consume' a reference count, like
     814                 :            : PyList_SetItem(), consume the reference even if the object wasn't
     815                 :            : successfully stored, to simplify error handling.
     816                 :            : 
     817                 :            : It seems attractive to make other functions that take an object as
     818                 :            : argument consume a reference count; however, this may quickly get
     819                 :            : confusing (even the current practice is already confusing).  Consider
     820                 :            : it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
     821                 :            : times.
     822                 :            : */
     823                 :            : 
     824                 :            : #ifndef Py_LIMITED_API
     825                 :            : #  define Py_CPYTHON_OBJECT_H
     826                 :            : #  include "cpython/object.h"
     827                 :            : #  undef Py_CPYTHON_OBJECT_H
     828                 :            : #endif
     829                 :            : 
     830                 :            : 
     831                 :            : static inline int
     832                 :   92253693 : PyType_HasFeature(PyTypeObject *type, unsigned long feature)
     833                 :            : {
     834                 :            :     unsigned long flags;
     835                 :            : #ifdef Py_LIMITED_API
     836                 :            :     // PyTypeObject is opaque in the limited C API
     837                 :          0 :     flags = PyType_GetFlags(type);
     838                 :            : #else
     839                 :   92253693 :     flags = type->tp_flags;
     840                 :            : #endif
     841                 :   92253693 :     return ((flags & feature) != 0);
     842                 :            : }
     843                 :            : 
     844                 :            : #define PyType_FastSubclass(type, flag) PyType_HasFeature((type), (flag))
     845                 :            : 
     846                 :    4180654 : static inline int PyType_Check(PyObject *op) {
     847                 :    4180654 :     return PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS);
     848                 :            : }
     849                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     850                 :            : #  define PyType_Check(op) PyType_Check(_PyObject_CAST(op))
     851                 :            : #endif
     852                 :            : 
     853                 :            : #define _PyType_CAST(op) \
     854                 :            :     (assert(PyType_Check(op)), _Py_CAST(PyTypeObject*, (op)))
     855                 :            : 
     856                 :     152457 : static inline int PyType_CheckExact(PyObject *op) {
     857                 :     152457 :     return Py_IS_TYPE(op, &PyType_Type);
     858                 :            : }
     859                 :            : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
     860                 :            : #  define PyType_CheckExact(op) PyType_CheckExact(_PyObject_CAST(op))
     861                 :            : #endif
     862                 :            : 
     863                 :            : #ifdef __cplusplus
     864                 :            : }
     865                 :            : #endif
     866                 :            : #endif   // !Py_OBJECT_H

Generated by: LCOV version 1.14