Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/python3.8/object.h @ 69:33d812a61356

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