Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.12/internal/pycore_object.h
1 #ifndef Py_INTERNAL_OBJECT_H 2 #define Py_INTERNAL_OBJECT_H 3 #ifdef __cplusplus 4 extern "C" { 5 #endif 6 7 #ifndef Py_BUILD_CORE 8 # error "this header requires Py_BUILD_CORE define" 9 #endif 10 11 #include <stdbool.h> 12 #include "pycore_gc.h" // _PyObject_GC_IS_TRACKED() 13 #include "pycore_interp.h" // PyInterpreterState.gc 14 #include "pycore_pystate.h" // _PyInterpreterState_GET() 15 #include "pycore_runtime.h" // _PyRuntime 16 17 /* We need to maintain an internal copy of Py{Var}Object_HEAD_INIT to avoid 18 designated initializer conflicts in C++20. If we use the deinition in 19 object.h, we will be mixing designated and non-designated initializers in 20 pycore objects which is forbiddent in C++20. However, if we then use 21 designated initializers in object.h then Extensions without designated break. 22 Furthermore, we can't use designated initializers in Extensions since these 23 are not supported pre-C++20. Thus, keeping an internal copy here is the most 24 backwards compatible solution */ 25 #define _PyObject_HEAD_INIT(type) \ 26 { \ 27 _PyObject_EXTRA_INIT \ 28 .ob_refcnt = _Py_IMMORTAL_REFCNT, \ 29 .ob_type = (type) \ 30 }, 31 #define _PyVarObject_HEAD_INIT(type, size) \ 32 { \ 33 .ob_base = _PyObject_HEAD_INIT(type) \ 34 .ob_size = size \ 35 }, 36 37 PyAPI_FUNC(void) _Py_NO_RETURN _Py_FatalRefcountErrorFunc( 38 const char *func, 39 const char *message); 40 41 #define _Py_FatalRefcountError(message) \ 42 _Py_FatalRefcountErrorFunc(__func__, (message)) 43 44 45 #ifdef Py_REF_DEBUG 46 /* The symbol is only exposed in the API for the sake of extensions 47 built against the pre-3.12 stable ABI. */ 48 PyAPI_DATA(Py_ssize_t) _Py_RefTotal; 49 50 extern void _Py_AddRefTotal(PyInterpreterState *, Py_ssize_t); 51 extern void _Py_IncRefTotal(PyInterpreterState *); 52 extern void _Py_DecRefTotal(PyInterpreterState *); 53 54 # define _Py_DEC_REFTOTAL(interp) \ 55 interp->object_state.reftotal-- 56 #endif 57 58 // Increment reference count by n 59 static inline void _Py_RefcntAdd(PyObject* op, Py_ssize_t n) 60 { 61 if (_Py_IsImmortal(op)) { 62 return; 63 } 64 #ifdef Py_REF_DEBUG 65 _Py_AddRefTotal(_PyInterpreterState_GET(), n); 66 #endif 67 op->ob_refcnt += n; 68 69 // Although the ref count was increased by `n` (which may be greater than 1) 70 // it is only a single increment (i.e. addition) operation, so only 1 refcnt 71 // increment operation is counted. 72 _Py_INCREF_STAT_INC(); 73 } 74 #define _Py_RefcntAdd(op, n) _Py_RefcntAdd(_PyObject_CAST(op), n) 75 76 static inline void _Py_SetImmortal(PyObject *op) 77 { 78 #ifdef Py_DEBUG 79 // For strings, use _PyUnicode_InternImmortal instead. 80 if (PyUnicode_CheckExact(op)) { 81 assert(PyUnicode_CHECK_INTERNED(op) == SSTATE_INTERNED_IMMORTAL 82 || PyUnicode_CHECK_INTERNED(op) == SSTATE_INTERNED_IMMORTAL_STATIC); 83 } 84 #endif 85 if (op) { 86 op->ob_refcnt = _Py_IMMORTAL_REFCNT; 87 } 88 } 89 #define _Py_SetImmortal(op) _Py_SetImmortal(_PyObject_CAST(op)) 90 91 /* _Py_ClearImmortal() should only be used during runtime finalization. */ 92 static inline void _Py_ClearImmortal(PyObject *op) 93 { 94 if (op) { 95 assert(_Py_IsImmortal(op)); 96 op->ob_refcnt = 1; 97 Py_DECREF(op); 98 } 99 } 100 #define _Py_ClearImmortal(op) \ 101 do { \ 102 _Py_ClearImmortal(_PyObject_CAST(op)); \ 103 op = NULL; \ 104 } while (0) 105 106 static inline void 107 _Py_DECREF_SPECIALIZED(PyObject *op, const destructor destruct) 108 { 109 if (_Py_IsImmortal(op)) { 110 return; 111 } 112 _Py_DECREF_STAT_INC(); 113 #ifdef Py_REF_DEBUG 114 _Py_DEC_REFTOTAL(_PyInterpreterState_GET()); 115 #endif 116 if (--op->ob_refcnt != 0) { 117 assert(op->ob_refcnt > 0); 118 } 119 else { 120 #ifdef Py_TRACE_REFS 121 _Py_ForgetReference(op); 122 #endif 123 destruct(op); 124 } 125 } 126 127 static inline void 128 _Py_DECREF_NO_DEALLOC(PyObject *op) 129 { 130 if (_Py_IsImmortal(op)) { 131 return; 132 } 133 _Py_DECREF_STAT_INC(); 134 #ifdef Py_REF_DEBUG 135 _Py_DEC_REFTOTAL(_PyInterpreterState_GET()); 136 #endif 137 op->ob_refcnt--; 138 #ifdef Py_DEBUG 139 if (op->ob_refcnt <= 0) { 140 _Py_FatalRefcountError("Expected a positive remaining refcount"); 141 } 142 #endif 143 } 144 145 #ifdef Py_REF_DEBUG 146 # undef _Py_DEC_REFTOTAL 147 #endif 148 149 150 PyAPI_FUNC(int) _PyType_CheckConsistency(PyTypeObject *type); 151 PyAPI_FUNC(int) _PyDict_CheckConsistency(PyObject *mp, int check_content); 152 153 /* Update the Python traceback of an object. This function must be called 154 when a memory block is reused from a free list. 155 156 Internal function called by _Py_NewReference(). */ 157 extern int _PyTraceMalloc_NewReference(PyObject *op); 158 159 // Fast inlined version of PyType_HasFeature() 160 static inline int 161 _PyType_HasFeature(PyTypeObject *type, unsigned long feature) { 162 return ((type->tp_flags & feature) != 0); 163 } 164 165 extern void _PyType_InitCache(PyInterpreterState *interp); 166 167 extern void _PyObject_InitState(PyInterpreterState *interp); 168 169 /* Inline functions trading binary compatibility for speed: 170 _PyObject_Init() is the fast version of PyObject_Init(), and 171 _PyObject_InitVar() is the fast version of PyObject_InitVar(). 172 173 These inline functions must not be called with op=NULL. */ 174 static inline void 175 _PyObject_Init(PyObject *op, PyTypeObject *typeobj) 176 { 177 assert(op != NULL); 178 Py_SET_TYPE(op, typeobj); 179 if (_PyType_HasFeature(typeobj, Py_TPFLAGS_HEAPTYPE)) { 180 Py_INCREF(typeobj); 181 } 182 _Py_NewReference(op); 183 } 184 185 static inline void 186 _PyObject_InitVar(PyVarObject *op, PyTypeObject *typeobj, Py_ssize_t size) 187 { 188 assert(op != NULL); 189 assert(typeobj != &PyLong_Type); 190 _PyObject_Init((PyObject *)op, typeobj); 191 Py_SET_SIZE(op, size); 192 } 193 194 195 /* Tell the GC to track this object. 196 * 197 * The object must not be tracked by the GC. 198 * 199 * NB: While the object is tracked by the collector, it must be safe to call the 200 * ob_traverse method. 201 * 202 * Internal note: interp->gc.generation0->_gc_prev doesn't have any bit flags 203 * because it's not object header. So we don't use _PyGCHead_PREV() and 204 * _PyGCHead_SET_PREV() for it to avoid unnecessary bitwise operations. 205 * 206 * See also the public PyObject_GC_Track() function. 207 */ 208 static inline void _PyObject_GC_TRACK( 209 // The preprocessor removes _PyObject_ASSERT_FROM() calls if NDEBUG is defined 210 #ifndef NDEBUG 211 const char *filename, int lineno, 212 #endif 213 PyObject *op) 214 { 215 _PyObject_ASSERT_FROM(op, !_PyObject_GC_IS_TRACKED(op), 216 "object already tracked by the garbage collector", 217 filename, lineno, __func__); 218 219 PyGC_Head *gc = _Py_AS_GC(op); 220 _PyObject_ASSERT_FROM(op, 221 (gc->_gc_prev & _PyGC_PREV_MASK_COLLECTING) == 0, 222 "object is in generation which is garbage collected", 223 filename, lineno, __func__); 224 225 PyInterpreterState *interp = _PyInterpreterState_GET(); 226 PyGC_Head *generation0 = interp->gc.generation0; 227 PyGC_Head *last = (PyGC_Head*)(generation0->_gc_prev); 228 _PyGCHead_SET_NEXT(last, gc); 229 _PyGCHead_SET_PREV(gc, last); 230 _PyGCHead_SET_NEXT(gc, generation0); 231 generation0->_gc_prev = (uintptr_t)gc; 232 } 233 234 /* Tell the GC to stop tracking this object. 235 * 236 * Internal note: This may be called while GC. So _PyGC_PREV_MASK_COLLECTING 237 * must be cleared. But _PyGC_PREV_MASK_FINALIZED bit is kept. 238 * 239 * The object must be tracked by the GC. 240 * 241 * See also the public PyObject_GC_UnTrack() which accept an object which is 242 * not tracked. 243 */ 244 static inline void _PyObject_GC_UNTRACK( 245 // The preprocessor removes _PyObject_ASSERT_FROM() calls if NDEBUG is defined 246 #ifndef NDEBUG 247 const char *filename, int lineno, 248 #endif 249 PyObject *op) 250 { 251 _PyObject_ASSERT_FROM(op, _PyObject_GC_IS_TRACKED(op), 252 "object not tracked by the garbage collector", 253 filename, lineno, __func__); 254 255 PyGC_Head *gc = _Py_AS_GC(op); 256 PyGC_Head *prev = _PyGCHead_PREV(gc); 257 PyGC_Head *next = _PyGCHead_NEXT(gc); 258 _PyGCHead_SET_NEXT(prev, next); 259 _PyGCHead_SET_PREV(next, prev); 260 gc->_gc_next = 0; 261 gc->_gc_prev &= _PyGC_PREV_MASK_FINALIZED; 262 } 263 264 // Macros to accept any type for the parameter, and to automatically pass 265 // the filename and the filename (if NDEBUG is not defined) where the macro 266 // is called. 267 #ifdef NDEBUG 268 # define _PyObject_GC_TRACK(op) \ 269 _PyObject_GC_TRACK(_PyObject_CAST(op)) 270 # define _PyObject_GC_UNTRACK(op) \ 271 _PyObject_GC_UNTRACK(_PyObject_CAST(op)) 272 #else 273 # define _PyObject_GC_TRACK(op) \ 274 _PyObject_GC_TRACK(__FILE__, __LINE__, _PyObject_CAST(op)) 275 # define _PyObject_GC_UNTRACK(op) \ 276 _PyObject_GC_UNTRACK(__FILE__, __LINE__, _PyObject_CAST(op)) 277 #endif 278 279 #ifdef Py_REF_DEBUG 280 extern void _PyInterpreterState_FinalizeRefTotal(PyInterpreterState *); 281 extern void _Py_FinalizeRefTotal(_PyRuntimeState *); 282 extern void _PyDebug_PrintTotalRefs(void); 283 #endif 284 285 #ifdef Py_TRACE_REFS 286 extern void _Py_AddToAllObjects(PyObject *op, int force); 287 extern void _Py_PrintReferences(PyInterpreterState *, FILE *); 288 extern void _Py_PrintReferenceAddresses(PyInterpreterState *, FILE *); 289 #endif 290 291 292 /* Return the *address* of the object's weaklist. The address may be 293 * dereferenced to get the current head of the weaklist. This is useful 294 * for iterating over the linked list of weakrefs, especially when the 295 * list is being modified externally (e.g. refs getting removed). 296 * 297 * The returned pointer should not be used to change the head of the list 298 * nor should it be used to add, remove, or swap any refs in the list. 299 * That is the sole responsibility of the code in weakrefobject.c. 300 */ 301 static inline PyObject ** 302 _PyObject_GET_WEAKREFS_LISTPTR(PyObject *op) 303 { 304 if (PyType_Check(op) && 305 ((PyTypeObject *)op)->tp_flags & _Py_TPFLAGS_STATIC_BUILTIN) { 306 PyInterpreterState *interp = _PyInterpreterState_GET(); 307 static_builtin_state *state = _PyStaticType_GetState( 308 interp, (PyTypeObject *)op); 309 return _PyStaticType_GET_WEAKREFS_LISTPTR(state); 310 } 311 // Essentially _PyObject_GET_WEAKREFS_LISTPTR_FROM_OFFSET(): 312 Py_ssize_t offset = Py_TYPE(op)->tp_weaklistoffset; 313 return (PyObject **)((char *)op + offset); 314 } 315 316 /* This is a special case of _PyObject_GET_WEAKREFS_LISTPTR(). 317 * Only the most fundamental lookup path is used. 318 * Consequently, static types should not be used. 319 * 320 * For static builtin types the returned pointer will always point 321 * to a NULL tp_weaklist. This is fine for any deallocation cases, 322 * since static types are never deallocated and static builtin types 323 * are only finalized at the end of runtime finalization. 324 * 325 * If the weaklist for static types is actually needed then use 326 * _PyObject_GET_WEAKREFS_LISTPTR(). 327 */ 328 static inline PyWeakReference ** 329 _PyObject_GET_WEAKREFS_LISTPTR_FROM_OFFSET(PyObject *op) 330 { 331 assert(!PyType_Check(op) || 332 ((PyTypeObject *)op)->tp_flags & Py_TPFLAGS_HEAPTYPE); 333 Py_ssize_t offset = Py_TYPE(op)->tp_weaklistoffset; 334 return (PyWeakReference **)((char *)op + offset); 335 } 336 337 338 // Fast inlined version of PyObject_IS_GC() 339 static inline int 340 _PyObject_IS_GC(PyObject *obj) 341 { 342 return (PyType_IS_GC(Py_TYPE(obj)) 343 && (Py_TYPE(obj)->tp_is_gc == NULL 344 || Py_TYPE(obj)->tp_is_gc(obj))); 345 } 346 347 // Fast inlined version of PyType_IS_GC() 348 #define _PyType_IS_GC(t) _PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC) 349 350 static inline size_t 351 _PyType_PreHeaderSize(PyTypeObject *tp) 352 { 353 return _PyType_IS_GC(tp) * sizeof(PyGC_Head) + 354 _PyType_HasFeature(tp, Py_TPFLAGS_PREHEADER) * 2 * sizeof(PyObject *); 355 } 356 357 void _PyObject_GC_Link(PyObject *op); 358 359 // Usage: assert(_Py_CheckSlotResult(obj, "__getitem__", result != NULL)); 360 extern int _Py_CheckSlotResult( 361 PyObject *obj, 362 const char *slot_name, 363 int success); 364 365 // Test if a type supports weak references 366 static inline int _PyType_SUPPORTS_WEAKREFS(PyTypeObject *type) { 367 return (type->tp_weaklistoffset != 0); 368 } 369 370 extern PyObject* _PyType_AllocNoTrack(PyTypeObject *type, Py_ssize_t nitems); 371 372 extern int _PyObject_InitializeDict(PyObject *obj); 373 extern int _PyObject_StoreInstanceAttribute(PyObject *obj, PyDictValues *values, 374 PyObject *name, PyObject *value); 375 PyObject * _PyObject_GetInstanceAttribute(PyObject *obj, PyDictValues *values, 376 PyObject *name); 377 378 typedef union { 379 PyObject *dict; 380 /* Use a char* to generate a warning if directly assigning a PyDictValues */ 381 char *values; 382 } PyDictOrValues; 383 384 static inline PyDictOrValues * 385 _PyObject_DictOrValuesPointer(PyObject *obj) 386 { 387 assert(Py_TYPE(obj)->tp_flags & Py_TPFLAGS_MANAGED_DICT); 388 return ((PyDictOrValues *)obj)-3; 389 } 390 391 static inline int 392 _PyDictOrValues_IsValues(PyDictOrValues dorv) 393 { 394 return ((uintptr_t)dorv.values) & 1; 395 } 396 397 static inline PyDictValues * 398 _PyDictOrValues_GetValues(PyDictOrValues dorv) 399 { 400 assert(_PyDictOrValues_IsValues(dorv)); 401 return (PyDictValues *)(dorv.values + 1); 402 } 403 404 static inline PyObject * 405 _PyDictOrValues_GetDict(PyDictOrValues dorv) 406 { 407 assert(!_PyDictOrValues_IsValues(dorv)); 408 return dorv.dict; 409 } 410 411 static inline void 412 _PyDictOrValues_SetValues(PyDictOrValues *ptr, PyDictValues *values) 413 { 414 ptr->values = ((char *)values) - 1; 415 } 416 417 #define MANAGED_WEAKREF_OFFSET (((Py_ssize_t)sizeof(PyObject *))*-4) 418 419 extern PyObject ** _PyObject_ComputedDictPointer(PyObject *); 420 extern void _PyObject_FreeInstanceAttributes(PyObject *obj); 421 extern int _PyObject_IsInstanceDictEmpty(PyObject *); 422 423 PyAPI_FUNC(PyObject *) _PyObject_LookupSpecial(PyObject *, PyObject *); 424 425 /* C function call trampolines to mitigate bad function pointer casts. 426 * 427 * Typical native ABIs ignore additional arguments or fill in missing 428 * values with 0/NULL in function pointer cast. Compilers do not show 429 * warnings when a function pointer is explicitly casted to an 430 * incompatible type. 431 * 432 * Bad fpcasts are an issue in WebAssembly. WASM's indirect_call has strict 433 * function signature checks. Argument count, types, and return type must 434 * match. 435 * 436 * Third party code unintentionally rely on problematic fpcasts. The call 437 * trampoline mitigates common occurrences of bad fpcasts on Emscripten. 438 */ 439 #if defined(__EMSCRIPTEN__) && defined(PY_CALL_TRAMPOLINE) 440 #define _PyCFunction_TrampolineCall(meth, self, args) \ 441 _PyCFunctionWithKeywords_TrampolineCall( \ 442 (*(PyCFunctionWithKeywords)(void(*)(void))(meth)), (self), (args), NULL) 443 extern PyObject* _PyCFunctionWithKeywords_TrampolineCall( 444 PyCFunctionWithKeywords meth, PyObject *, PyObject *, PyObject *); 445 #else 446 #define _PyCFunction_TrampolineCall(meth, self, args) \ 447 (meth)((self), (args)) 448 #define _PyCFunctionWithKeywords_TrampolineCall(meth, self, args, kw) \ 449 (meth)((self), (args), (kw)) 450 #endif // __EMSCRIPTEN__ && PY_CALL_TRAMPOLINE 451 452 #ifdef __cplusplus 453 } 454 #endif 455 #endif /* !Py_INTERNAL_OBJECT_H */
