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 7 #ifdef Py_TRACE_REFS 8 /* Py_TRACE_REFS is such major surgery that we call external routines. */ 9 PyAPI_FUNC(void) _Py_ForgetReference(PyObject *); 10 #endif 11 12 #ifdef Py_REF_DEBUG 13 PyAPI_FUNC(Py_ssize_t) _Py_GetRefTotal(void); 14 #endif 15 16 17 /********************* String Literals ****************************************/ 18 /* This structure helps managing static strings. The basic usage goes like this: 19 Instead of doing 20 21 r = PyObject_CallMethod(o, "foo", "args", ...); 22 23 do 24 25 _Py_IDENTIFIER(foo); 26 ... 27 r = _PyObject_CallMethodId(o, &PyId_foo, "args", ...); 28 29 PyId_foo is a static variable, either on block level or file level. On first 30 usage, the string "foo" is interned, and the structures are linked. On interpreter 31 shutdown, all strings are released. 32 33 Alternatively, _Py_static_string allows choosing the variable name. 34 _PyUnicode_FromId returns a borrowed reference to the interned string. 35 _PyObject_{Get,Set,Has}AttrId are __getattr__ versions using _Py_Identifier*. 36 */ 37 typedef struct _Py_Identifier { 38 const char* string; 39 // Index in PyInterpreterState.unicode.ids.array. It is process-wide 40 // unique and must be initialized to -1. 41 Py_ssize_t index; 42 } _Py_Identifier; 43 44 #define _Py_static_string_init(value) { .string = value, .index = -1 } 45 #define _Py_static_string(varname, value) static _Py_Identifier varname = _Py_static_string_init(value) 46 #define _Py_IDENTIFIER(varname) _Py_static_string(PyId_##varname, #varname) 47 48 /* buffer interface */ 49 typedef struct bufferinfo { 50 void *buf; 51 PyObject *obj; /* owned reference */ 52 Py_ssize_t len; 53 Py_ssize_t itemsize; /* This is Py_ssize_t so it can be 54 pointed to by strides in simple case.*/ 55 int readonly; 56 int ndim; 57 char *format; 58 Py_ssize_t *shape; 59 Py_ssize_t *strides; 60 Py_ssize_t *suboffsets; 61 void *internal; 62 } Py_buffer; 63 64 typedef int (*getbufferproc)(PyObject *, Py_buffer *, int); 65 typedef void (*releasebufferproc)(PyObject *, Py_buffer *); 66 67 typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, 68 size_t nargsf, PyObject *kwnames); 69 70 /* Maximum number of dimensions */ 71 #define PyBUF_MAX_NDIM 64 72 73 /* Flags for getting buffers */ 74 #define PyBUF_SIMPLE 0 75 #define PyBUF_WRITABLE 0x0001 76 /* we used to include an E, backwards compatible alias */ 77 #define PyBUF_WRITEABLE PyBUF_WRITABLE 78 #define PyBUF_FORMAT 0x0004 79 #define PyBUF_ND 0x0008 80 #define PyBUF_STRIDES (0x0010 | PyBUF_ND) 81 #define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES) 82 #define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES) 83 #define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES) 84 #define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES) 85 86 #define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE) 87 #define PyBUF_CONTIG_RO (PyBUF_ND) 88 89 #define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE) 90 #define PyBUF_STRIDED_RO (PyBUF_STRIDES) 91 92 #define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT) 93 #define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT) 94 95 #define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT) 96 #define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT) 97 98 99 #define PyBUF_READ 0x100 100 #define PyBUF_WRITE 0x200 101 /* End buffer interface */ 102 103 104 typedef struct { 105 /* Number implementations must check *both* 106 arguments for proper type and implement the necessary conversions 107 in the slot functions themselves. */ 108 109 binaryfunc nb_add; 110 binaryfunc nb_subtract; 111 binaryfunc nb_multiply; 112 binaryfunc nb_remainder; 113 binaryfunc nb_divmod; 114 ternaryfunc nb_power; 115 unaryfunc nb_negative; 116 unaryfunc nb_positive; 117 unaryfunc nb_absolute; 118 inquiry nb_bool; 119 unaryfunc nb_invert; 120 binaryfunc nb_lshift; 121 binaryfunc nb_rshift; 122 binaryfunc nb_and; 123 binaryfunc nb_xor; 124 binaryfunc nb_or; 125 unaryfunc nb_int; 126 void *nb_reserved; /* the slot formerly known as nb_long */ 127 unaryfunc nb_float; 128 129 binaryfunc nb_inplace_add; 130 binaryfunc nb_inplace_subtract; 131 binaryfunc nb_inplace_multiply; 132 binaryfunc nb_inplace_remainder; 133 ternaryfunc nb_inplace_power; 134 binaryfunc nb_inplace_lshift; 135 binaryfunc nb_inplace_rshift; 136 binaryfunc nb_inplace_and; 137 binaryfunc nb_inplace_xor; 138 binaryfunc nb_inplace_or; 139 140 binaryfunc nb_floor_divide; 141 binaryfunc nb_true_divide; 142 binaryfunc nb_inplace_floor_divide; 143 binaryfunc nb_inplace_true_divide; 144 145 unaryfunc nb_index; 146 147 binaryfunc nb_matrix_multiply; 148 binaryfunc nb_inplace_matrix_multiply; 149 } PyNumberMethods; 150 151 typedef struct { 152 lenfunc sq_length; 153 binaryfunc sq_concat; 154 ssizeargfunc sq_repeat; 155 ssizeargfunc sq_item; 156 void *was_sq_slice; 157 ssizeobjargproc sq_ass_item; 158 void *was_sq_ass_slice; 159 objobjproc sq_contains; 160 161 binaryfunc sq_inplace_concat; 162 ssizeargfunc sq_inplace_repeat; 163 } PySequenceMethods; 164 165 typedef struct { 166 lenfunc mp_length; 167 binaryfunc mp_subscript; 168 objobjargproc mp_ass_subscript; 169 } PyMappingMethods; 170 171 typedef PySendResult (*sendfunc)(PyObject *iter, PyObject *value, PyObject **result); 172 173 typedef struct { 174 unaryfunc am_await; 175 unaryfunc am_aiter; 176 unaryfunc am_anext; 177 sendfunc am_send; 178 } PyAsyncMethods; 179 180 typedef struct { 181 getbufferproc bf_getbuffer; 182 releasebufferproc bf_releasebuffer; 183 } PyBufferProcs; 184 185 /* Allow printfunc in the tp_vectorcall_offset slot for 186 * backwards-compatibility */ 187 typedef Py_ssize_t printfunc; 188 189 // If this structure is modified, Doc/includes/typestruct.h should be updated 190 // as well. 191 struct _typeobject { 192 PyObject_VAR_HEAD 193 const char *tp_name; /* For printing, in format "<module>.<name>" */ 194 Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */ 195 196 /* Methods to implement standard operations */ 197 198 destructor tp_dealloc; 199 Py_ssize_t tp_vectorcall_offset; 200 getattrfunc tp_getattr; 201 setattrfunc tp_setattr; 202 PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2) 203 or tp_reserved (Python 3) */ 204 reprfunc tp_repr; 205 206 /* Method suites for standard classes */ 207 208 PyNumberMethods *tp_as_number; 209 PySequenceMethods *tp_as_sequence; 210 PyMappingMethods *tp_as_mapping; 211 212 /* More standard operations (here for binary compatibility) */ 213 214 hashfunc tp_hash; 215 ternaryfunc tp_call; 216 reprfunc tp_str; 217 getattrofunc tp_getattro; 218 setattrofunc tp_setattro; 219 220 /* Functions to access object as input/output buffer */ 221 PyBufferProcs *tp_as_buffer; 222 223 /* Flags to define presence of optional/expanded features */ 224 unsigned long tp_flags; 225 226 const char *tp_doc; /* Documentation string */ 227 228 /* Assigned meaning in release 2.0 */ 229 /* call function for all accessible objects */ 230 traverseproc tp_traverse; 231 232 /* delete references to contained objects */ 233 inquiry tp_clear; 234 235 /* Assigned meaning in release 2.1 */ 236 /* rich comparisons */ 237 richcmpfunc tp_richcompare; 238 239 /* weak reference enabler */ 240 Py_ssize_t tp_weaklistoffset; 241 242 /* Iterators */ 243 getiterfunc tp_iter; 244 iternextfunc tp_iternext; 245 246 /* Attribute descriptor and subclassing stuff */ 247 struct PyMethodDef *tp_methods; 248 struct PyMemberDef *tp_members; 249 struct PyGetSetDef *tp_getset; 250 // Strong reference on a heap type, borrowed reference on a static type 251 struct _typeobject *tp_base; 252 PyObject *tp_dict; 253 descrgetfunc tp_descr_get; 254 descrsetfunc tp_descr_set; 255 Py_ssize_t tp_dictoffset; 256 initproc tp_init; 257 allocfunc tp_alloc; 258 newfunc tp_new; 259 freefunc tp_free; /* Low-level free-memory routine */ 260 inquiry tp_is_gc; /* For PyObject_IS_GC */ 261 PyObject *tp_bases; 262 PyObject *tp_mro; /* method resolution order */ 263 PyObject *tp_cache; 264 PyObject *tp_subclasses; 265 PyObject *tp_weaklist; 266 destructor tp_del; 267 268 /* Type attribute cache version tag. Added in version 2.6 */ 269 unsigned int tp_version_tag; 270 271 destructor tp_finalize; 272 vectorcallfunc tp_vectorcall; 273 }; 274 275 /* The *real* layout of a type object when allocated on the heap */ 276 typedef struct _heaptypeobject { 277 /* Note: there's a dependency on the order of these members 278 in slotptr() in typeobject.c . */ 279 PyTypeObject ht_type; 280 PyAsyncMethods as_async; 281 PyNumberMethods as_number; 282 PyMappingMethods as_mapping; 283 PySequenceMethods as_sequence; /* as_sequence comes after as_mapping, 284 so that the mapping wins when both 285 the mapping and the sequence define 286 a given operator (e.g. __getitem__). 287 see add_operators() in typeobject.c . */ 288 PyBufferProcs as_buffer; 289 PyObject *ht_name, *ht_slots, *ht_qualname; 290 struct _dictkeysobject *ht_cached_keys; 291 PyObject *ht_module; 292 char *_ht_tpname; // Storage for "tp_name"; see PyType_FromModuleAndSpec 293 /* here are optional user slots, followed by the members. */ 294 } PyHeapTypeObject; 295 296 /* access macro to the members which are floating "behind" the object */ 297 #define PyHeapType_GET_MEMBERS(etype) \ 298 ((PyMemberDef *)(((char *)etype) + Py_TYPE(etype)->tp_basicsize)) 299 300 PyAPI_FUNC(const char *) _PyType_Name(PyTypeObject *); 301 PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *); 302 PyAPI_FUNC(PyObject *) _PyType_LookupId(PyTypeObject *, _Py_Identifier *); 303 PyAPI_FUNC(PyObject *) _PyObject_LookupSpecial(PyObject *, _Py_Identifier *); 304 PyAPI_FUNC(PyTypeObject *) _PyType_CalculateMetaclass(PyTypeObject *, PyObject *); 305 PyAPI_FUNC(PyObject *) _PyType_GetDocFromInternalDoc(const char *, const char *); 306 PyAPI_FUNC(PyObject *) _PyType_GetTextSignatureFromInternalDoc(const char *, const char *); 307 struct PyModuleDef; 308 PyAPI_FUNC(PyObject *) _PyType_GetModuleByDef(PyTypeObject *, struct PyModuleDef *); 309 310 struct _Py_Identifier; 311 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int); 312 PyAPI_FUNC(void) _Py_BreakPoint(void); 313 PyAPI_FUNC(void) _PyObject_Dump(PyObject *); 314 PyAPI_FUNC(int) _PyObject_IsFreed(PyObject *); 315 316 PyAPI_FUNC(int) _PyObject_IsAbstract(PyObject *); 317 PyAPI_FUNC(PyObject *) _PyObject_GetAttrId(PyObject *, struct _Py_Identifier *); 318 PyAPI_FUNC(int) _PyObject_SetAttrId(PyObject *, struct _Py_Identifier *, PyObject *); 319 /* Replacements of PyObject_GetAttr() and _PyObject_GetAttrId() which 320 don't raise AttributeError. 321 322 Return 1 and set *result != NULL if an attribute is found. 323 Return 0 and set *result == NULL if an attribute is not found; 324 an AttributeError is silenced. 325 Return -1 and set *result == NULL if an error other than AttributeError 326 is raised. 327 */ 328 PyAPI_FUNC(int) _PyObject_LookupAttr(PyObject *, PyObject *, PyObject **); 329 PyAPI_FUNC(int) _PyObject_LookupAttrId(PyObject *, struct _Py_Identifier *, PyObject **); 330 331 PyAPI_FUNC(int) _PyObject_GetMethod(PyObject *obj, PyObject *name, PyObject **method); 332 333 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *); 334 PyAPI_FUNC(PyObject *) _PyObject_NextNotImplemented(PyObject *); 335 PyAPI_FUNC(void) PyObject_CallFinalizer(PyObject *); 336 PyAPI_FUNC(int) PyObject_CallFinalizerFromDealloc(PyObject *); 337 338 /* Same as PyObject_Generic{Get,Set}Attr, but passing the attributes 339 dict as the last parameter. */ 340 PyAPI_FUNC(PyObject *) 341 _PyObject_GenericGetAttrWithDict(PyObject *, PyObject *, PyObject *, int); 342 PyAPI_FUNC(int) 343 _PyObject_GenericSetAttrWithDict(PyObject *, PyObject *, 344 PyObject *, PyObject *); 345 346 PyAPI_FUNC(PyObject *) _PyObject_FunctionStr(PyObject *); 347 348 /* Safely decref `op` and set `op` to `op2`. 349 * 350 * As in case of Py_CLEAR "the obvious" code can be deadly: 351 * 352 * Py_DECREF(op); 353 * op = op2; 354 * 355 * The safe way is: 356 * 357 * Py_SETREF(op, op2); 358 * 359 * That arranges to set `op` to `op2` _before_ decref'ing, so that any code 360 * triggered as a side-effect of `op` getting torn down no longer believes 361 * `op` points to a valid object. 362 * 363 * Py_XSETREF is a variant of Py_SETREF that uses Py_XDECREF instead of 364 * Py_DECREF. 365 */ 366 367 #define Py_SETREF(op, op2) \ 368 do { \ 369 PyObject *_py_tmp = _PyObject_CAST(op); \ 370 (op) = (op2); \ 371 Py_DECREF(_py_tmp); \ 372 } while (0) 373 374 #define Py_XSETREF(op, op2) \ 375 do { \ 376 PyObject *_py_tmp = _PyObject_CAST(op); \ 377 (op) = (op2); \ 378 Py_XDECREF(_py_tmp); \ 379 } while (0) 380 381 382 PyAPI_DATA(PyTypeObject) _PyNone_Type; 383 PyAPI_DATA(PyTypeObject) _PyNotImplemented_Type; 384 385 /* Maps Py_LT to Py_GT, ..., Py_GE to Py_LE. 386 * Defined in object.c. 387 */ 388 PyAPI_DATA(int) _Py_SwappedOp[]; 389 390 PyAPI_FUNC(void) 391 _PyDebugAllocatorStats(FILE *out, const char *block_name, int num_blocks, 392 size_t sizeof_block); 393 PyAPI_FUNC(void) 394 _PyObject_DebugTypeStats(FILE *out); 395 396 /* Define a pair of assertion macros: 397 _PyObject_ASSERT_FROM(), _PyObject_ASSERT_WITH_MSG() and _PyObject_ASSERT(). 398 399 These work like the regular C assert(), in that they will abort the 400 process with a message on stderr if the given condition fails to hold, 401 but compile away to nothing if NDEBUG is defined. 402 403 However, before aborting, Python will also try to call _PyObject_Dump() on 404 the given object. This may be of use when investigating bugs in which a 405 particular object is corrupt (e.g. buggy a tp_visit method in an extension 406 module breaking the garbage collector), to help locate the broken objects. 407 408 The WITH_MSG variant allows you to supply an additional message that Python 409 will attempt to print to stderr, after the object dump. */ 410 #ifdef NDEBUG 411 /* No debugging: compile away the assertions: */ 412 # define _PyObject_ASSERT_FROM(obj, expr, msg, filename, lineno, func) \ 413 ((void)0) 414 #else 415 /* With debugging: generate checks: */ 416 # define _PyObject_ASSERT_FROM(obj, expr, msg, filename, lineno, func) \ 417 ((expr) \ 418 ? (void)(0) \ 419 : _PyObject_AssertFailed((obj), Py_STRINGIFY(expr), \ 420 (msg), (filename), (lineno), (func))) 421 #endif 422 423 #define _PyObject_ASSERT_WITH_MSG(obj, expr, msg) \ 424 _PyObject_ASSERT_FROM(obj, expr, msg, __FILE__, __LINE__, __func__) 425 #define _PyObject_ASSERT(obj, expr) \ 426 _PyObject_ASSERT_WITH_MSG(obj, expr, NULL) 427 428 #define _PyObject_ASSERT_FAILED_MSG(obj, msg) \ 429 _PyObject_AssertFailed((obj), NULL, (msg), __FILE__, __LINE__, __func__) 430 431 /* Declare and define _PyObject_AssertFailed() even when NDEBUG is defined, 432 to avoid causing compiler/linker errors when building extensions without 433 NDEBUG against a Python built with NDEBUG defined. 434 435 msg, expr and function can be NULL. */ 436 PyAPI_FUNC(void) _Py_NO_RETURN _PyObject_AssertFailed( 437 PyObject *obj, 438 const char *expr, 439 const char *msg, 440 const char *file, 441 int line, 442 const char *function); 443 444 /* Check if an object is consistent. For example, ensure that the reference 445 counter is greater than or equal to 1, and ensure that ob_type is not NULL. 446 447 Call _PyObject_AssertFailed() if the object is inconsistent. 448 449 If check_content is zero, only check header fields: reduce the overhead. 450 451 The function always return 1. The return value is just here to be able to 452 write: 453 454 assert(_PyObject_CheckConsistency(obj, 1)); */ 455 PyAPI_FUNC(int) _PyObject_CheckConsistency( 456 PyObject *op, 457 int check_content); 458 459 460 /* Trashcan mechanism, thanks to Christian Tismer. 461 462 When deallocating a container object, it's possible to trigger an unbounded 463 chain of deallocations, as each Py_DECREF in turn drops the refcount on "the 464 next" object in the chain to 0. This can easily lead to stack overflows, 465 especially in threads (which typically have less stack space to work with). 466 467 A container object can avoid this by bracketing the body of its tp_dealloc 468 function with a pair of macros: 469 470 static void 471 mytype_dealloc(mytype *p) 472 { 473 ... declarations go here ... 474 475 PyObject_GC_UnTrack(p); // must untrack first 476 Py_TRASHCAN_BEGIN(p, mytype_dealloc) 477 ... The body of the deallocator goes here, including all calls ... 478 ... to Py_DECREF on contained objects. ... 479 Py_TRASHCAN_END // there should be no code after this 480 } 481 482 CAUTION: Never return from the middle of the body! If the body needs to 483 "get out early", put a label immediately before the Py_TRASHCAN_END 484 call, and goto it. Else the call-depth counter (see below) will stay 485 above 0 forever, and the trashcan will never get emptied. 486 487 How it works: The BEGIN macro increments a call-depth counter. So long 488 as this counter is small, the body of the deallocator is run directly without 489 further ado. But if the counter gets large, it instead adds p to a list of 490 objects to be deallocated later, skips the body of the deallocator, and 491 resumes execution after the END macro. The tp_dealloc routine then returns 492 without deallocating anything (and so unbounded call-stack depth is avoided). 493 494 When the call stack finishes unwinding again, code generated by the END macro 495 notices this, and calls another routine to deallocate all the objects that 496 may have been added to the list of deferred deallocations. In effect, a 497 chain of N deallocations is broken into (N-1)/(_PyTrash_UNWIND_LEVEL-1) pieces, 498 with the call stack never exceeding a depth of _PyTrash_UNWIND_LEVEL. 499 500 Since the tp_dealloc of a subclass typically calls the tp_dealloc of the base 501 class, we need to ensure that the trashcan is only triggered on the tp_dealloc 502 of the actual class being deallocated. Otherwise we might end up with a 503 partially-deallocated object. To check this, the tp_dealloc function must be 504 passed as second argument to Py_TRASHCAN_BEGIN(). 505 */ 506 507 /* Forward declarations for PyThreadState */ 508 struct _ts; 509 510 /* Python 3.9 private API, invoked by the macros below. */ 511 PyAPI_FUNC(int) _PyTrash_begin(struct _ts *tstate, PyObject *op); 512 PyAPI_FUNC(void) _PyTrash_end(struct _ts *tstate); 513 /* Python 3.10 private API, invoked by the Py_TRASHCAN_BEGIN(). */ 514 PyAPI_FUNC(int) _PyTrash_cond(PyObject *op, destructor dealloc); 515 516 #define Py_TRASHCAN_BEGIN_CONDITION(op, cond) \ 517 do { \ 518 PyThreadState *_tstate = NULL; \ 519 /* If "cond" is false, then _tstate remains NULL and the deallocator \ 520 * is run normally without involving the trashcan */ \ 521 if (cond) { \ 522 _tstate = PyThreadState_Get(); \ 523 if (_PyTrash_begin(_tstate, _PyObject_CAST(op))) { \ 524 break; \ 525 } \ 526 } 527 /* The body of the deallocator is here. */ 528 #define Py_TRASHCAN_END \ 529 if (_tstate) { \ 530 _PyTrash_end(_tstate); \ 531 } \ 532 } while (0); 533 534 #define Py_TRASHCAN_BEGIN(op, dealloc) \ 535 Py_TRASHCAN_BEGIN_CONDITION(op, \ 536 _PyTrash_cond(_PyObject_CAST(op), (destructor)dealloc)) 537 538 /* The following two macros, Py_TRASHCAN_SAFE_BEGIN and 539 * Py_TRASHCAN_SAFE_END, are deprecated since version 3.11 and 540 * will be removed in the future. 541 * Use Py_TRASHCAN_BEGIN and Py_TRASHCAN_END instead. 542 */ 543 Py_DEPRECATED(3.11) typedef int UsingDeprecatedTrashcanMacro; 544 #define Py_TRASHCAN_SAFE_BEGIN(op) \ 545 do { \ 546 UsingDeprecatedTrashcanMacro cond=1; \ 547 Py_TRASHCAN_BEGIN_CONDITION(op, cond); 548 #define Py_TRASHCAN_SAFE_END(op) \ 549 Py_TRASHCAN_END; \ 550 } while(0); 551