Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.14/cpython/object.h
1 #ifndef Py_CPYTHON_OBJECT_H 2 # error "this header file must not be included directly" 3 #endif 4 5 PyAPI_FUNC(void) _Py_NewReference(PyObject *op); 6 PyAPI_FUNC(void) _Py_NewReferenceNoTotal(PyObject *op); 7 PyAPI_FUNC(void) _Py_ResurrectReference(PyObject *op); 8 PyAPI_FUNC(void) _Py_ForgetReference(PyObject *op); 9 10 #ifdef Py_REF_DEBUG 11 /* These are useful as debugging aids when chasing down refleaks. */ 12 PyAPI_FUNC(Py_ssize_t) _Py_GetGlobalRefTotal(void); 13 # define _Py_GetRefTotal() _Py_GetGlobalRefTotal() 14 PyAPI_FUNC(Py_ssize_t) _Py_GetLegacyRefTotal(void); 15 PyAPI_FUNC(Py_ssize_t) _PyInterpreterState_GetRefTotal(PyInterpreterState *); 16 #endif 17 18 19 /********************* String Literals ****************************************/ 20 /* This structure helps managing static strings. The basic usage goes like this: 21 Instead of doing 22 23 r = PyObject_CallMethod(o, "foo", "args", ...); 24 25 do 26 27 _Py_IDENTIFIER(foo); 28 ... 29 r = _PyObject_CallMethodId(o, &PyId_foo, "args", ...); 30 31 PyId_foo is a static variable, either on block level or file level. On first 32 usage, the string "foo" is interned, and the structures are linked. On interpreter 33 shutdown, all strings are released. 34 35 Alternatively, _Py_static_string allows choosing the variable name. 36 _PyUnicode_FromId returns a borrowed reference to the interned string. 37 _PyObject_{Get,Set,Has}AttrId are __getattr__ versions using _Py_Identifier*. 38 */ 39 typedef struct _Py_Identifier { 40 const char* string; 41 // Index in PyInterpreterState.unicode.ids.array. It is process-wide 42 // unique and must be initialized to -1. 43 Py_ssize_t index; 44 // Hidden PyMutex struct for non free-threaded build. 45 struct { 46 uint8_t v; 47 } mutex; 48 } _Py_Identifier; 49 50 #ifndef Py_BUILD_CORE 51 // For now we are keeping _Py_IDENTIFIER for continued use 52 // in non-builtin extensions (and naughty PyPI modules). 53 54 #define _Py_static_string_init(value) { .string = (value), .index = -1 } 55 #define _Py_static_string(varname, value) static _Py_Identifier varname = _Py_static_string_init(value) 56 #define _Py_IDENTIFIER(varname) _Py_static_string(PyId_##varname, #varname) 57 58 #endif /* !Py_BUILD_CORE */ 59 60 61 typedef struct { 62 /* Number implementations must check *both* 63 arguments for proper type and implement the necessary conversions 64 in the slot functions themselves. */ 65 66 binaryfunc nb_add; 67 binaryfunc nb_subtract; 68 binaryfunc nb_multiply; 69 binaryfunc nb_remainder; 70 binaryfunc nb_divmod; 71 ternaryfunc nb_power; 72 unaryfunc nb_negative; 73 unaryfunc nb_positive; 74 unaryfunc nb_absolute; 75 inquiry nb_bool; 76 unaryfunc nb_invert; 77 binaryfunc nb_lshift; 78 binaryfunc nb_rshift; 79 binaryfunc nb_and; 80 binaryfunc nb_xor; 81 binaryfunc nb_or; 82 unaryfunc nb_int; 83 void *nb_reserved; /* the slot formerly known as nb_long */ 84 unaryfunc nb_float; 85 86 binaryfunc nb_inplace_add; 87 binaryfunc nb_inplace_subtract; 88 binaryfunc nb_inplace_multiply; 89 binaryfunc nb_inplace_remainder; 90 ternaryfunc nb_inplace_power; 91 binaryfunc nb_inplace_lshift; 92 binaryfunc nb_inplace_rshift; 93 binaryfunc nb_inplace_and; 94 binaryfunc nb_inplace_xor; 95 binaryfunc nb_inplace_or; 96 97 binaryfunc nb_floor_divide; 98 binaryfunc nb_true_divide; 99 binaryfunc nb_inplace_floor_divide; 100 binaryfunc nb_inplace_true_divide; 101 102 unaryfunc nb_index; 103 104 binaryfunc nb_matrix_multiply; 105 binaryfunc nb_inplace_matrix_multiply; 106 } PyNumberMethods; 107 108 typedef struct { 109 lenfunc sq_length; 110 binaryfunc sq_concat; 111 ssizeargfunc sq_repeat; 112 ssizeargfunc sq_item; 113 void *was_sq_slice; 114 ssizeobjargproc sq_ass_item; 115 void *was_sq_ass_slice; 116 objobjproc sq_contains; 117 118 binaryfunc sq_inplace_concat; 119 ssizeargfunc sq_inplace_repeat; 120 } PySequenceMethods; 121 122 typedef struct { 123 lenfunc mp_length; 124 binaryfunc mp_subscript; 125 objobjargproc mp_ass_subscript; 126 } PyMappingMethods; 127 128 typedef PySendResult (*sendfunc)(PyObject *iter, PyObject *value, PyObject **result); 129 130 typedef struct { 131 unaryfunc am_await; 132 unaryfunc am_aiter; 133 unaryfunc am_anext; 134 sendfunc am_send; 135 } PyAsyncMethods; 136 137 typedef struct { 138 getbufferproc bf_getbuffer; 139 releasebufferproc bf_releasebuffer; 140 } PyBufferProcs; 141 142 /* Allow printfunc in the tp_vectorcall_offset slot for 143 * backwards-compatibility */ 144 typedef Py_ssize_t printfunc; 145 146 // If this structure is modified, Doc/includes/typestruct.h should be updated 147 // as well. 148 struct _typeobject { 149 PyObject_VAR_HEAD 150 const char *tp_name; /* For printing, in format "<module>.<name>" */ 151 Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */ 152 153 /* Methods to implement standard operations */ 154 155 destructor tp_dealloc; 156 Py_ssize_t tp_vectorcall_offset; 157 getattrfunc tp_getattr; 158 setattrfunc tp_setattr; 159 PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2) 160 or tp_reserved (Python 3) */ 161 reprfunc tp_repr; 162 163 /* Method suites for standard classes */ 164 165 PyNumberMethods *tp_as_number; 166 PySequenceMethods *tp_as_sequence; 167 PyMappingMethods *tp_as_mapping; 168 169 /* More standard operations (here for binary compatibility) */ 170 171 hashfunc tp_hash; 172 ternaryfunc tp_call; 173 reprfunc tp_str; 174 getattrofunc tp_getattro; 175 setattrofunc tp_setattro; 176 177 /* Functions to access object as input/output buffer */ 178 PyBufferProcs *tp_as_buffer; 179 180 /* Flags to define presence of optional/expanded features */ 181 unsigned long tp_flags; 182 183 const char *tp_doc; /* Documentation string */ 184 185 /* Assigned meaning in release 2.0 */ 186 /* call function for all accessible objects */ 187 traverseproc tp_traverse; 188 189 /* delete references to contained objects */ 190 inquiry tp_clear; 191 192 /* Assigned meaning in release 2.1 */ 193 /* rich comparisons */ 194 richcmpfunc tp_richcompare; 195 196 /* weak reference enabler */ 197 Py_ssize_t tp_weaklistoffset; 198 199 /* Iterators */ 200 getiterfunc tp_iter; 201 iternextfunc tp_iternext; 202 203 /* Attribute descriptor and subclassing stuff */ 204 PyMethodDef *tp_methods; 205 PyMemberDef *tp_members; 206 PyGetSetDef *tp_getset; 207 // Strong reference on a heap type, borrowed reference on a static type 208 PyTypeObject *tp_base; 209 PyObject *tp_dict; 210 descrgetfunc tp_descr_get; 211 descrsetfunc tp_descr_set; 212 Py_ssize_t tp_dictoffset; 213 initproc tp_init; 214 allocfunc tp_alloc; 215 newfunc tp_new; 216 freefunc tp_free; /* Low-level free-memory routine */ 217 inquiry tp_is_gc; /* For PyObject_IS_GC */ 218 PyObject *tp_bases; 219 PyObject *tp_mro; /* method resolution order */ 220 PyObject *tp_cache; /* no longer used */ 221 void *tp_subclasses; /* for static builtin types this is an index */ 222 PyObject *tp_weaklist; /* not used for static builtin types */ 223 destructor tp_del; 224 225 /* Type attribute cache version tag. Added in version 2.6. 226 * If zero, the cache is invalid and must be initialized. 227 */ 228 unsigned int tp_version_tag; 229 230 destructor tp_finalize; 231 vectorcallfunc tp_vectorcall; 232 233 /* bitset of which type-watchers care about this type */ 234 unsigned char tp_watched; 235 236 /* Number of tp_version_tag values used. 237 * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is 238 * disabled for this type (e.g. due to custom MRO entries). 239 * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere). 240 */ 241 uint16_t tp_versions_used; 242 }; 243 244 #define _Py_ATTR_CACHE_UNUSED (30000) // (see tp_versions_used) 245 246 /* This struct is used by the specializer 247 * It should be treated as an opaque blob 248 * by code other than the specializer and interpreter. */ 249 struct _specialization_cache { 250 // In order to avoid bloating the bytecode with lots of inline caches, the 251 // members of this structure have a somewhat unique contract. They are set 252 // by the specialization machinery, and are invalidated by PyType_Modified. 253 // The rules for using them are as follows: 254 // - If getitem is non-NULL, then it is the same Python function that 255 // PyType_Lookup(cls, "__getitem__") would return. 256 // - If getitem is NULL, then getitem_version is meaningless. 257 // - If getitem->func_version == getitem_version, then getitem can be called 258 // with two positional arguments and no keyword arguments, and has neither 259 // *args nor **kwargs (as required by BINARY_OP_SUBSCR_GETITEM): 260 PyObject *getitem; 261 uint32_t getitem_version; 262 PyObject *init; 263 }; 264 265 /* The *real* layout of a type object when allocated on the heap */ 266 typedef struct _heaptypeobject { 267 /* Note: there's a dependency on the order of these members 268 in slotptr() in typeobject.c . */ 269 PyTypeObject ht_type; 270 PyAsyncMethods as_async; 271 PyNumberMethods as_number; 272 PyMappingMethods as_mapping; 273 PySequenceMethods as_sequence; /* as_sequence comes after as_mapping, 274 so that the mapping wins when both 275 the mapping and the sequence define 276 a given operator (e.g. __getitem__). 277 see add_operators() in typeobject.c . */ 278 PyBufferProcs as_buffer; 279 PyObject *ht_name, *ht_slots, *ht_qualname; 280 struct _dictkeysobject *ht_cached_keys; 281 PyObject *ht_module; 282 char *_ht_tpname; // Storage for "tp_name"; see PyType_FromModuleAndSpec 283 void *ht_token; // Storage for the "Py_tp_token" slot 284 struct _specialization_cache _spec_cache; // For use by the specializer. 285 #ifdef Py_GIL_DISABLED 286 Py_ssize_t unique_id; // ID used for per-thread refcounting 287 #endif 288 /* here are optional user slots, followed by the members. */ 289 } PyHeapTypeObject; 290 291 PyAPI_FUNC(const char *) _PyType_Name(PyTypeObject *); 292 PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *); 293 PyAPI_FUNC(PyObject *) _PyType_LookupRef(PyTypeObject *, PyObject *); 294 PyAPI_FUNC(PyObject *) PyType_GetDict(PyTypeObject *); 295 296 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int); 297 PyAPI_FUNC(void) _Py_BreakPoint(void); 298 PyAPI_FUNC(void) _PyObject_Dump(PyObject *); 299 300 PyAPI_FUNC(PyObject*) _PyObject_GetAttrId(PyObject *, _Py_Identifier *); 301 302 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *); 303 PyAPI_FUNC(void) PyObject_CallFinalizer(PyObject *); 304 PyAPI_FUNC(int) PyObject_CallFinalizerFromDealloc(PyObject *); 305 306 PyAPI_FUNC(void) PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *); 307 308 /* Same as PyObject_Generic{Get,Set}Attr, but passing the attributes 309 dict as the last parameter. */ 310 PyAPI_FUNC(PyObject *) 311 _PyObject_GenericGetAttrWithDict(PyObject *, PyObject *, PyObject *, int); 312 PyAPI_FUNC(int) 313 _PyObject_GenericSetAttrWithDict(PyObject *, PyObject *, 314 PyObject *, PyObject *); 315 316 PyAPI_FUNC(PyObject *) _PyObject_FunctionStr(PyObject *); 317 318 /* Safely decref `dst` and set `dst` to `src`. 319 * 320 * As in case of Py_CLEAR "the obvious" code can be deadly: 321 * 322 * Py_DECREF(dst); 323 * dst = src; 324 * 325 * The safe way is: 326 * 327 * Py_SETREF(dst, src); 328 * 329 * That arranges to set `dst` to `src` _before_ decref'ing, so that any code 330 * triggered as a side-effect of `dst` getting torn down no longer believes 331 * `dst` points to a valid object. 332 * 333 * Temporary variables are used to only evaluate macro arguments once and so 334 * avoid the duplication of side effects. _Py_TYPEOF() or memcpy() is used to 335 * avoid a miscompilation caused by type punning. See Py_CLEAR() comment for 336 * implementation details about type punning. 337 * 338 * The memcpy() implementation does not emit a compiler warning if 'src' has 339 * not the same type than 'src': any pointer type is accepted for 'src'. 340 */ 341 #ifdef _Py_TYPEOF 342 #define Py_SETREF(dst, src) \ 343 do { \ 344 _Py_TYPEOF(dst)* _tmp_dst_ptr = &(dst); \ 345 _Py_TYPEOF(dst) _tmp_old_dst = (*_tmp_dst_ptr); \ 346 *_tmp_dst_ptr = (src); \ 347 Py_DECREF(_tmp_old_dst); \ 348 } while (0) 349 #else 350 #define Py_SETREF(dst, src) \ 351 do { \ 352 PyObject **_tmp_dst_ptr = _Py_CAST(PyObject**, &(dst)); \ 353 PyObject *_tmp_old_dst = (*_tmp_dst_ptr); \ 354 PyObject *_tmp_src = _PyObject_CAST(src); \ 355 memcpy(_tmp_dst_ptr, &_tmp_src, sizeof(PyObject*)); \ 356 Py_DECREF(_tmp_old_dst); \ 357 } while (0) 358 #endif 359 360 /* Py_XSETREF() is a variant of Py_SETREF() that uses Py_XDECREF() instead of 361 * Py_DECREF(). 362 */ 363 #ifdef _Py_TYPEOF 364 #define Py_XSETREF(dst, src) \ 365 do { \ 366 _Py_TYPEOF(dst)* _tmp_dst_ptr = &(dst); \ 367 _Py_TYPEOF(dst) _tmp_old_dst = (*_tmp_dst_ptr); \ 368 *_tmp_dst_ptr = (src); \ 369 Py_XDECREF(_tmp_old_dst); \ 370 } while (0) 371 #else 372 #define Py_XSETREF(dst, src) \ 373 do { \ 374 PyObject **_tmp_dst_ptr = _Py_CAST(PyObject**, &(dst)); \ 375 PyObject *_tmp_old_dst = (*_tmp_dst_ptr); \ 376 PyObject *_tmp_src = _PyObject_CAST(src); \ 377 memcpy(_tmp_dst_ptr, &_tmp_src, sizeof(PyObject*)); \ 378 Py_XDECREF(_tmp_old_dst); \ 379 } while (0) 380 #endif 381 382 383 /* Define a pair of assertion macros: 384 _PyObject_ASSERT_FROM(), _PyObject_ASSERT_WITH_MSG() and _PyObject_ASSERT(). 385 386 These work like the regular C assert(), in that they will abort the 387 process with a message on stderr if the given condition fails to hold, 388 but compile away to nothing if NDEBUG is defined. 389 390 However, before aborting, Python will also try to call _PyObject_Dump() on 391 the given object. This may be of use when investigating bugs in which a 392 particular object is corrupt (e.g. buggy a tp_visit method in an extension 393 module breaking the garbage collector), to help locate the broken objects. 394 395 The WITH_MSG variant allows you to supply an additional message that Python 396 will attempt to print to stderr, after the object dump. */ 397 #ifdef NDEBUG 398 /* No debugging: compile away the assertions: */ 399 # define _PyObject_ASSERT_FROM(obj, expr, msg, filename, lineno, func) \ 400 ((void)0) 401 #else 402 /* With debugging: generate checks: */ 403 # define _PyObject_ASSERT_FROM(obj, expr, msg, filename, lineno, func) \ 404 ((expr) \ 405 ? (void)(0) \ 406 : _PyObject_AssertFailed((obj), Py_STRINGIFY(expr), \ 407 (msg), (filename), (lineno), (func))) 408 #endif 409 410 #define _PyObject_ASSERT_WITH_MSG(obj, expr, msg) \ 411 _PyObject_ASSERT_FROM((obj), expr, (msg), __FILE__, __LINE__, __func__) 412 #define _PyObject_ASSERT(obj, expr) \ 413 _PyObject_ASSERT_WITH_MSG((obj), expr, NULL) 414 415 #define _PyObject_ASSERT_FAILED_MSG(obj, msg) \ 416 _PyObject_AssertFailed((obj), NULL, (msg), __FILE__, __LINE__, __func__) 417 418 /* Declare and define _PyObject_AssertFailed() even when NDEBUG is defined, 419 to avoid causing compiler/linker errors when building extensions without 420 NDEBUG against a Python built with NDEBUG defined. 421 422 msg, expr and function can be NULL. */ 423 PyAPI_FUNC(void) _Py_NO_RETURN _PyObject_AssertFailed( 424 PyObject *obj, 425 const char *expr, 426 const char *msg, 427 const char *file, 428 int line, 429 const char *function); 430 431 432 PyAPI_FUNC(void) _PyTrash_thread_deposit_object(PyThreadState *tstate, PyObject *op); 433 PyAPI_FUNC(void) _PyTrash_thread_destroy_chain(PyThreadState *tstate); 434 435 PyAPI_FUNC(int) _Py_ReachedRecursionLimitWithMargin(PyThreadState *tstate, int margin_count); 436 437 /* For backwards compatibility with the old trashcan mechanism */ 438 #define Py_TRASHCAN_BEGIN(op, dealloc) 439 #define Py_TRASHCAN_END 440 441 442 PyAPI_FUNC(void *) PyObject_GetItemData(PyObject *obj); 443 444 PyAPI_FUNC(int) PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg); 445 PyAPI_FUNC(int) _PyObject_SetManagedDict(PyObject *obj, PyObject *new_dict); 446 PyAPI_FUNC(void) PyObject_ClearManagedDict(PyObject *obj); 447 448 449 typedef int(*PyType_WatchCallback)(PyTypeObject *); 450 PyAPI_FUNC(int) PyType_AddWatcher(PyType_WatchCallback callback); 451 PyAPI_FUNC(int) PyType_ClearWatcher(int watcher_id); 452 PyAPI_FUNC(int) PyType_Watch(int watcher_id, PyObject *type); 453 PyAPI_FUNC(int) PyType_Unwatch(int watcher_id, PyObject *type); 454 455 /* Attempt to assign a version tag to the given type. 456 * 457 * Returns 1 if the type already had a valid version tag or a new one was 458 * assigned, or 0 if a new tag could not be assigned. 459 */ 460 PyAPI_FUNC(int) PyUnstable_Type_AssignVersionTag(PyTypeObject *type); 461 462 463 typedef enum { 464 PyRefTracer_CREATE = 0, 465 PyRefTracer_DESTROY = 1, 466 } PyRefTracerEvent; 467 468 typedef int (*PyRefTracer)(PyObject *, PyRefTracerEvent event, void *); 469 PyAPI_FUNC(int) PyRefTracer_SetTracer(PyRefTracer tracer, void *data); 470 PyAPI_FUNC(PyRefTracer) PyRefTracer_GetTracer(void**); 471 472 /* Enable PEP-703 deferred reference counting on the object. 473 * 474 * Returns 1 if deferred reference counting was successfully enabled, and 475 * 0 if the runtime ignored it. This function cannot fail. 476 */ 477 PyAPI_FUNC(int) PyUnstable_Object_EnableDeferredRefcount(PyObject *); 478 479 /* Determine if the object exists as a unique temporary variable on the 480 * topmost frame of the interpreter. 481 */ 482 PyAPI_FUNC(int) PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *); 483 484 /* Check whether the object is immortal. This cannot fail. */ 485 PyAPI_FUNC(int) PyUnstable_IsImmortal(PyObject *); 486 487 // Increments the reference count of the object, if it's not zero. 488 // PyUnstable_EnableTryIncRef() should be called on the object 489 // before calling this function in order to avoid spurious failures. 490 PyAPI_FUNC(int) PyUnstable_TryIncRef(PyObject *); 491 PyAPI_FUNC(void) PyUnstable_EnableTryIncRef(PyObject *); 492 493 PyAPI_FUNC(int) PyUnstable_Object_IsUniquelyReferenced(PyObject *);
