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 /* Py_DEBUG implies Py_TRACE_REFS. */ 55 #if defined(Py_DEBUG) && !defined(Py_TRACE_REFS) 56 #define Py_TRACE_REFS 57 #endif 58 59 /* Py_TRACE_REFS implies Py_REF_DEBUG. */ 60 #if defined(Py_TRACE_REFS) && !defined(Py_REF_DEBUG) 61 #define Py_REF_DEBUG 62 #endif 63 64 #if defined(Py_LIMITED_API) && defined(Py_REF_DEBUG) 65 #error Py_LIMITED_API is incompatible with Py_DEBUG, Py_TRACE_REFS, and Py_REF_DEBUG 66 #endif 67 68 69 #ifdef Py_TRACE_REFS 70 /* Define pointers to support a doubly-linked list of all live heap objects. */ 71 #define _PyObject_HEAD_EXTRA \ 72 struct _object *_ob_next; \ 73 struct _object *_ob_prev; 74 75 #define _PyObject_EXTRA_INIT 0, 0, 76 77 #else 78 #define _PyObject_HEAD_EXTRA 79 #define _PyObject_EXTRA_INIT 80 #endif 81 82 /* PyObject_HEAD defines the initial segment of every PyObject. */ 83 #define PyObject_HEAD PyObject ob_base; 84 85 #define PyObject_HEAD_INIT(type) \ 86 { _PyObject_EXTRA_INIT \ 87 1, type }, 88 89 #define PyVarObject_HEAD_INIT(type, size) \ 90 { PyObject_HEAD_INIT(type) size }, 91 92 /* PyObject_VAR_HEAD defines the initial segment of all variable-size 93 * container objects. These end with a declaration of an array with 1 94 * element, but enough space is malloc'ed so that the array actually 95 * has room for ob_size elements. Note that ob_size is an element count, 96 * not necessarily a byte count. 97 */ 98 #define PyObject_VAR_HEAD PyVarObject ob_base; 99 #define Py_INVALID_SIZE (Py_ssize_t)-1 100 101 /* Nothing is actually declared to be a PyObject, but every pointer to 102 * a Python object can be cast to a PyObject*. This is inheritance built 103 * by hand. Similarly every pointer to a variable-size Python object can, 104 * in addition, be cast to PyVarObject*. 105 */ 106 typedef struct _object { 107 _PyObject_HEAD_EXTRA 108 Py_ssize_t ob_refcnt; 109 struct _typeobject *ob_type; 110 } PyObject; 111 112 typedef struct { 113 PyObject ob_base; 114 Py_ssize_t ob_size; /* Number of items in variable part */ 115 } PyVarObject; 116 117 #define Py_REFCNT(ob) (((PyObject*)(ob))->ob_refcnt) 118 #define Py_TYPE(ob) (((PyObject*)(ob))->ob_type) 119 #define Py_SIZE(ob) (((PyVarObject*)(ob))->ob_size) 120 121 #ifndef Py_LIMITED_API 122 /********************* String Literals ****************************************/ 123 /* This structure helps managing static strings. The basic usage goes like this: 124 Instead of doing 125 126 r = PyObject_CallMethod(o, "foo", "args", ...); 127 128 do 129 130 _Py_IDENTIFIER(foo); 131 ... 132 r = _PyObject_CallMethodId(o, &PyId_foo, "args", ...); 133 134 PyId_foo is a static variable, either on block level or file level. On first 135 usage, the string "foo" is interned, and the structures are linked. On interpreter 136 shutdown, all strings are released (through _PyUnicode_ClearStaticStrings). 137 138 Alternatively, _Py_static_string allows choosing the variable name. 139 _PyUnicode_FromId returns a borrowed reference to the interned string. 140 _PyObject_{Get,Set,Has}AttrId are __getattr__ versions using _Py_Identifier*. 141 */ 142 typedef struct _Py_Identifier { 143 struct _Py_Identifier *next; 144 const char* string; 145 PyObject *object; 146 } _Py_Identifier; 147 148 #define _Py_static_string_init(value) { .next = NULL, .string = value, .object = NULL } 149 #define _Py_static_string(varname, value) static _Py_Identifier varname = _Py_static_string_init(value) 150 #define _Py_IDENTIFIER(varname) _Py_static_string(PyId_##varname, #varname) 151 152 #endif /* !Py_LIMITED_API */ 153 154 /* 155 Type objects contain a string containing the type name (to help somewhat 156 in debugging), the allocation parameters (see PyObject_New() and 157 PyObject_NewVar()), 158 and methods for accessing objects of the type. Methods are optional, a 159 nil pointer meaning that particular kind of access is not available for 160 this type. The Py_DECREF() macro uses the tp_dealloc method without 161 checking for a nil pointer; it should always be implemented except if 162 the implementation can guarantee that the reference count will never 163 reach zero (e.g., for statically allocated type objects). 164 165 NB: the methods for certain type groups are now contained in separate 166 method blocks. 167 */ 168 169 typedef PyObject * (*unaryfunc)(PyObject *); 170 typedef PyObject * (*binaryfunc)(PyObject *, PyObject *); 171 typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *); 172 typedef int (*inquiry)(PyObject *); 173 typedef Py_ssize_t (*lenfunc)(PyObject *); 174 typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t); 175 typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t); 176 typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *); 177 typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *); 178 typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *); 179 180 #ifndef Py_LIMITED_API 181 /* buffer interface */ 182 typedef struct bufferinfo { 183 void *buf; 184 PyObject *obj; /* owned reference */ 185 Py_ssize_t len; 186 Py_ssize_t itemsize; /* This is Py_ssize_t so it can be 187 pointed to by strides in simple case.*/ 188 int readonly; 189 int ndim; 190 char *format; 191 Py_ssize_t *shape; 192 Py_ssize_t *strides; 193 Py_ssize_t *suboffsets; 194 void *internal; 195 } Py_buffer; 196 197 typedef int (*getbufferproc)(PyObject *, Py_buffer *, int); 198 typedef void (*releasebufferproc)(PyObject *, Py_buffer *); 199 200 /* Maximum number of dimensions */ 201 #define PyBUF_MAX_NDIM 64 202 203 /* Flags for getting buffers */ 204 #define PyBUF_SIMPLE 0 205 #define PyBUF_WRITABLE 0x0001 206 /* we used to include an E, backwards compatible alias */ 207 #define PyBUF_WRITEABLE PyBUF_WRITABLE 208 #define PyBUF_FORMAT 0x0004 209 #define PyBUF_ND 0x0008 210 #define PyBUF_STRIDES (0x0010 | PyBUF_ND) 211 #define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES) 212 #define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES) 213 #define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES) 214 #define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES) 215 216 #define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE) 217 #define PyBUF_CONTIG_RO (PyBUF_ND) 218 219 #define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE) 220 #define PyBUF_STRIDED_RO (PyBUF_STRIDES) 221 222 #define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT) 223 #define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT) 224 225 #define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT) 226 #define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT) 227 228 229 #define PyBUF_READ 0x100 230 #define PyBUF_WRITE 0x200 231 232 /* End buffer interface */ 233 #endif /* Py_LIMITED_API */ 234 235 typedef int (*objobjproc)(PyObject *, PyObject *); 236 typedef int (*visitproc)(PyObject *, void *); 237 typedef int (*traverseproc)(PyObject *, visitproc, void *); 238 239 #ifndef Py_LIMITED_API 240 typedef struct { 241 /* Number implementations must check *both* 242 arguments for proper type and implement the necessary conversions 243 in the slot functions themselves. */ 244 245 binaryfunc nb_add; 246 binaryfunc nb_subtract; 247 binaryfunc nb_multiply; 248 binaryfunc nb_remainder; 249 binaryfunc nb_divmod; 250 ternaryfunc nb_power; 251 unaryfunc nb_negative; 252 unaryfunc nb_positive; 253 unaryfunc nb_absolute; 254 inquiry nb_bool; 255 unaryfunc nb_invert; 256 binaryfunc nb_lshift; 257 binaryfunc nb_rshift; 258 binaryfunc nb_and; 259 binaryfunc nb_xor; 260 binaryfunc nb_or; 261 unaryfunc nb_int; 262 void *nb_reserved; /* the slot formerly known as nb_long */ 263 unaryfunc nb_float; 264 265 binaryfunc nb_inplace_add; 266 binaryfunc nb_inplace_subtract; 267 binaryfunc nb_inplace_multiply; 268 binaryfunc nb_inplace_remainder; 269 ternaryfunc nb_inplace_power; 270 binaryfunc nb_inplace_lshift; 271 binaryfunc nb_inplace_rshift; 272 binaryfunc nb_inplace_and; 273 binaryfunc nb_inplace_xor; 274 binaryfunc nb_inplace_or; 275 276 binaryfunc nb_floor_divide; 277 binaryfunc nb_true_divide; 278 binaryfunc nb_inplace_floor_divide; 279 binaryfunc nb_inplace_true_divide; 280 281 unaryfunc nb_index; 282 283 binaryfunc nb_matrix_multiply; 284 binaryfunc nb_inplace_matrix_multiply; 285 } PyNumberMethods; 286 287 typedef struct { 288 lenfunc sq_length; 289 binaryfunc sq_concat; 290 ssizeargfunc sq_repeat; 291 ssizeargfunc sq_item; 292 void *was_sq_slice; 293 ssizeobjargproc sq_ass_item; 294 void *was_sq_ass_slice; 295 objobjproc sq_contains; 296 297 binaryfunc sq_inplace_concat; 298 ssizeargfunc sq_inplace_repeat; 299 } PySequenceMethods; 300 301 typedef struct { 302 lenfunc mp_length; 303 binaryfunc mp_subscript; 304 objobjargproc mp_ass_subscript; 305 } PyMappingMethods; 306 307 typedef struct { 308 unaryfunc am_await; 309 unaryfunc am_aiter; 310 unaryfunc am_anext; 311 } PyAsyncMethods; 312 313 typedef struct { 314 getbufferproc bf_getbuffer; 315 releasebufferproc bf_releasebuffer; 316 } PyBufferProcs; 317 #endif /* Py_LIMITED_API */ 318 319 typedef void (*freefunc)(void *); 320 typedef void (*destructor)(PyObject *); 321 #ifndef Py_LIMITED_API 322 /* We can't provide a full compile-time check that limited-API 323 users won't implement tp_print. However, not defining printfunc 324 and making tp_print of a different function pointer type 325 should at least cause a warning in most cases. */ 326 typedef int (*printfunc)(PyObject *, FILE *, int); 327 #endif 328 typedef PyObject *(*getattrfunc)(PyObject *, char *); 329 typedef PyObject *(*getattrofunc)(PyObject *, PyObject *); 330 typedef int (*setattrfunc)(PyObject *, char *, PyObject *); 331 typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *); 332 typedef PyObject *(*reprfunc)(PyObject *); 333 typedef Py_hash_t (*hashfunc)(PyObject *); 334 typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int); 335 typedef PyObject *(*getiterfunc) (PyObject *); 336 typedef PyObject *(*iternextfunc) (PyObject *); 337 typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *); 338 typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *); 339 typedef int (*initproc)(PyObject *, PyObject *, PyObject *); 340 typedef PyObject *(*newfunc)(struct _typeobject *, PyObject *, PyObject *); 341 typedef PyObject *(*allocfunc)(struct _typeobject *, Py_ssize_t); 342 343 #ifdef Py_LIMITED_API 344 typedef struct _typeobject PyTypeObject; /* opaque */ 345 #else 346 typedef struct _typeobject { 347 PyObject_VAR_HEAD 348 const char *tp_name; /* For printing, in format "<module>.<name>" */ 349 Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */ 350 351 /* Methods to implement standard operations */ 352 353 destructor tp_dealloc; 354 printfunc tp_print; 355 getattrfunc tp_getattr; 356 setattrfunc tp_setattr; 357 PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2) 358 or tp_reserved (Python 3) */ 359 reprfunc tp_repr; 360 361 /* Method suites for standard classes */ 362 363 PyNumberMethods *tp_as_number; 364 PySequenceMethods *tp_as_sequence; 365 PyMappingMethods *tp_as_mapping; 366 367 /* More standard operations (here for binary compatibility) */ 368 369 hashfunc tp_hash; 370 ternaryfunc tp_call; 371 reprfunc tp_str; 372 getattrofunc tp_getattro; 373 setattrofunc tp_setattro; 374 375 /* Functions to access object as input/output buffer */ 376 PyBufferProcs *tp_as_buffer; 377 378 /* Flags to define presence of optional/expanded features */ 379 unsigned long tp_flags; 380 381 const char *tp_doc; /* Documentation string */ 382 383 /* Assigned meaning in release 2.0 */ 384 /* call function for all accessible objects */ 385 traverseproc tp_traverse; 386 387 /* delete references to contained objects */ 388 inquiry tp_clear; 389 390 /* Assigned meaning in release 2.1 */ 391 /* rich comparisons */ 392 richcmpfunc tp_richcompare; 393 394 /* weak reference enabler */ 395 Py_ssize_t tp_weaklistoffset; 396 397 /* Iterators */ 398 getiterfunc tp_iter; 399 iternextfunc tp_iternext; 400 401 /* Attribute descriptor and subclassing stuff */ 402 struct PyMethodDef *tp_methods; 403 struct PyMemberDef *tp_members; 404 struct PyGetSetDef *tp_getset; 405 struct _typeobject *tp_base; 406 PyObject *tp_dict; 407 descrgetfunc tp_descr_get; 408 descrsetfunc tp_descr_set; 409 Py_ssize_t tp_dictoffset; 410 initproc tp_init; 411 allocfunc tp_alloc; 412 newfunc tp_new; 413 freefunc tp_free; /* Low-level free-memory routine */ 414 inquiry tp_is_gc; /* For PyObject_IS_GC */ 415 PyObject *tp_bases; 416 PyObject *tp_mro; /* method resolution order */ 417 PyObject *tp_cache; 418 PyObject *tp_subclasses; 419 PyObject *tp_weaklist; 420 destructor tp_del; 421 422 /* Type attribute cache version tag. Added in version 2.6 */ 423 unsigned int tp_version_tag; 424 425 destructor tp_finalize; 426 427 #ifdef COUNT_ALLOCS 428 /* these must be last and never explicitly initialized */ 429 Py_ssize_t tp_allocs; 430 Py_ssize_t tp_frees; 431 Py_ssize_t tp_maxalloc; 432 struct _typeobject *tp_prev; 433 struct _typeobject *tp_next; 434 #endif 435 } PyTypeObject; 436 #endif 437 438 typedef struct{ 439 int slot; /* slot id, see below */ 440 void *pfunc; /* function pointer */ 441 } PyType_Slot; 442 443 typedef struct{ 444 const char* name; 445 int basicsize; 446 int itemsize; 447 unsigned int flags; 448 PyType_Slot *slots; /* terminated by slot==0. */ 449 } PyType_Spec; 450 451 PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*); 452 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 453 PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*); 454 #endif 455 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000 456 PyAPI_FUNC(void*) PyType_GetSlot(PyTypeObject*, int); 457 #endif 458 459 #ifndef Py_LIMITED_API 460 /* The *real* layout of a type object when allocated on the heap */ 461 typedef struct _heaptypeobject { 462 /* Note: there's a dependency on the order of these members 463 in slotptr() in typeobject.c . */ 464 PyTypeObject ht_type; 465 PyAsyncMethods as_async; 466 PyNumberMethods as_number; 467 PyMappingMethods as_mapping; 468 PySequenceMethods as_sequence; /* as_sequence comes after as_mapping, 469 so that the mapping wins when both 470 the mapping and the sequence define 471 a given operator (e.g. __getitem__). 472 see add_operators() in typeobject.c . */ 473 PyBufferProcs as_buffer; 474 PyObject *ht_name, *ht_slots, *ht_qualname; 475 struct _dictkeysobject *ht_cached_keys; 476 /* here are optional user slots, followed by the members. */ 477 } PyHeapTypeObject; 478 479 /* access macro to the members which are floating "behind" the object */ 480 #define PyHeapType_GET_MEMBERS(etype) \ 481 ((PyMemberDef *)(((char *)etype) + Py_TYPE(etype)->tp_basicsize)) 482 #endif 483 484 /* Generic type check */ 485 PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *); 486 #define PyObject_TypeCheck(ob, tp) \ 487 (Py_TYPE(ob) == (tp) || PyType_IsSubtype(Py_TYPE(ob), (tp))) 488 489 PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */ 490 PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */ 491 PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */ 492 493 PyAPI_FUNC(unsigned long) PyType_GetFlags(PyTypeObject*); 494 495 #define PyType_Check(op) \ 496 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS) 497 #define PyType_CheckExact(op) (Py_TYPE(op) == &PyType_Type) 498 499 PyAPI_FUNC(int) PyType_Ready(PyTypeObject *); 500 PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t); 501 PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *, 502 PyObject *, PyObject *); 503 #ifndef Py_LIMITED_API 504 PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *); 505 PyAPI_FUNC(PyObject *) _PyType_LookupId(PyTypeObject *, _Py_Identifier *); 506 PyAPI_FUNC(PyObject *) _PyObject_LookupSpecial(PyObject *, _Py_Identifier *); 507 PyAPI_FUNC(PyTypeObject *) _PyType_CalculateMetaclass(PyTypeObject *, PyObject *); 508 #endif 509 PyAPI_FUNC(unsigned int) PyType_ClearCache(void); 510 PyAPI_FUNC(void) PyType_Modified(PyTypeObject *); 511 512 #ifndef Py_LIMITED_API 513 PyAPI_FUNC(PyObject *) _PyType_GetDocFromInternalDoc(const char *, const char *); 514 PyAPI_FUNC(PyObject *) _PyType_GetTextSignatureFromInternalDoc(const char *, const char *); 515 #endif 516 517 /* Generic operations on objects */ 518 #ifndef Py_LIMITED_API 519 struct _Py_Identifier; 520 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int); 521 PyAPI_FUNC(void) _Py_BreakPoint(void); 522 PyAPI_FUNC(void) _PyObject_Dump(PyObject *); 523 #endif 524 PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *); 525 PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *); 526 PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *); 527 PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *); 528 PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int); 529 PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int); 530 PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *); 531 PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *); 532 PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *); 533 PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *); 534 PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *); 535 PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *); 536 #ifndef Py_LIMITED_API 537 PyAPI_FUNC(int) _PyObject_IsAbstract(PyObject *); 538 PyAPI_FUNC(PyObject *) _PyObject_GetAttrId(PyObject *, struct _Py_Identifier *); 539 PyAPI_FUNC(int) _PyObject_SetAttrId(PyObject *, struct _Py_Identifier *, PyObject *); 540 PyAPI_FUNC(int) _PyObject_HasAttrId(PyObject *, struct _Py_Identifier *); 541 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *); 542 #endif 543 PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *); 544 #ifndef Py_LIMITED_API 545 PyAPI_FUNC(PyObject *) _PyObject_NextNotImplemented(PyObject *); 546 #endif 547 PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *); 548 PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, 549 PyObject *, PyObject *); 550 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 551 PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *); 552 #endif 553 PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *); 554 PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *); 555 PyAPI_FUNC(int) PyObject_IsTrue(PyObject *); 556 PyAPI_FUNC(int) PyObject_Not(PyObject *); 557 PyAPI_FUNC(int) PyCallable_Check(PyObject *); 558 559 PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *); 560 #ifndef Py_LIMITED_API 561 PyAPI_FUNC(void) PyObject_CallFinalizer(PyObject *); 562 PyAPI_FUNC(int) PyObject_CallFinalizerFromDealloc(PyObject *); 563 #endif 564 565 #ifndef Py_LIMITED_API 566 /* Same as PyObject_Generic{Get,Set}Attr, but passing the attributes 567 dict as the last parameter. */ 568 PyAPI_FUNC(PyObject *) 569 _PyObject_GenericGetAttrWithDict(PyObject *, PyObject *, PyObject *); 570 PyAPI_FUNC(int) 571 _PyObject_GenericSetAttrWithDict(PyObject *, PyObject *, 572 PyObject *, PyObject *); 573 #endif /* !Py_LIMITED_API */ 574 575 /* Helper to look up a builtin object */ 576 #ifndef Py_LIMITED_API 577 PyAPI_FUNC(PyObject *) 578 _PyObject_GetBuiltin(const char *name); 579 #endif 580 581 /* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a 582 list of strings. PyObject_Dir(NULL) is like builtins.dir(), 583 returning the names of the current locals. In this case, if there are 584 no current locals, NULL is returned, and PyErr_Occurred() is false. 585 */ 586 PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *); 587 588 589 /* Helpers for printing recursive container types */ 590 PyAPI_FUNC(int) Py_ReprEnter(PyObject *); 591 PyAPI_FUNC(void) Py_ReprLeave(PyObject *); 592 593 /* Flag bits for printing: */ 594 #define Py_PRINT_RAW 1 /* No string quotes etc. */ 595 596 /* 597 `Type flags (tp_flags) 598 599 These flags are used to extend the type structure in a backwards-compatible 600 fashion. Extensions can use the flags to indicate (and test) when a given 601 type structure contains a new feature. The Python core will use these when 602 introducing new functionality between major revisions (to avoid mid-version 603 changes in the PYTHON_API_VERSION). 604 605 Arbitration of the flag bit positions will need to be coordinated among 606 all extension writers who publically release their extensions (this will 607 be fewer than you might expect!).. 608 609 Most flags were removed as of Python 3.0 to make room for new flags. (Some 610 flags are not for backwards compatibility but to indicate the presence of an 611 optional feature; these flags remain of course.) 612 613 Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value. 614 615 Code can use PyType_HasFeature(type_ob, flag_value) to test whether the 616 given type object has a specified feature. 617 */ 618 619 /* Set if the type object is dynamically allocated */ 620 #define Py_TPFLAGS_HEAPTYPE (1UL << 9) 621 622 /* Set if the type allows subclassing */ 623 #define Py_TPFLAGS_BASETYPE (1UL << 10) 624 625 /* Set if the type is 'ready' -- fully initialized */ 626 #define Py_TPFLAGS_READY (1UL << 12) 627 628 /* Set while the type is being 'readied', to prevent recursive ready calls */ 629 #define Py_TPFLAGS_READYING (1UL << 13) 630 631 /* Objects support garbage collection (see objimp.h) */ 632 #define Py_TPFLAGS_HAVE_GC (1UL << 14) 633 634 /* These two bits are preserved for Stackless Python, next after this is 17 */ 635 #ifdef STACKLESS 636 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15) 637 #else 638 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0 639 #endif 640 641 /* Objects support type attribute cache */ 642 #define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18) 643 #define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19) 644 645 /* Type is abstract and cannot be instantiated */ 646 #define Py_TPFLAGS_IS_ABSTRACT (1UL << 20) 647 648 /* These flags are used to determine if a type is a subclass. */ 649 #define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24) 650 #define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25) 651 #define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26) 652 #define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27) 653 #define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28) 654 #define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29) 655 #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30) 656 #define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31) 657 658 #define Py_TPFLAGS_DEFAULT ( \ 659 Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \ 660 Py_TPFLAGS_HAVE_VERSION_TAG | \ 661 0) 662 663 /* NOTE: The following flags reuse lower bits (removed as part of the 664 * Python 3.0 transition). */ 665 666 /* Type structure has tp_finalize member (3.4) */ 667 #define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0) 668 669 #ifdef Py_LIMITED_API 670 #define PyType_HasFeature(t,f) ((PyType_GetFlags(t) & (f)) != 0) 671 #else 672 #define PyType_HasFeature(t,f) (((t)->tp_flags & (f)) != 0) 673 #endif 674 #define PyType_FastSubclass(t,f) PyType_HasFeature(t,f) 675 676 677 /* 678 The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement 679 reference counts. Py_DECREF calls the object's deallocator function when 680 the refcount falls to 0; for 681 objects that don't contain references to other objects or heap memory 682 this can be the standard function free(). Both macros can be used 683 wherever a void expression is allowed. The argument must not be a 684 NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead. 685 The macro _Py_NewReference(op) initialize reference counts to 1, and 686 in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional 687 bookkeeping appropriate to the special build. 688 689 We assume that the reference count field can never overflow; this can 690 be proven when the size of the field is the same as the pointer size, so 691 we ignore the possibility. Provided a C int is at least 32 bits (which 692 is implicitly assumed in many parts of this code), that's enough for 693 about 2**31 references to an object. 694 695 XXX The following became out of date in Python 2.2, but I'm not sure 696 XXX what the full truth is now. Certainly, heap-allocated type objects 697 XXX can and should be deallocated. 698 Type objects should never be deallocated; the type pointer in an object 699 is not considered to be a reference to the type object, to save 700 complications in the deallocation function. (This is actually a 701 decision that's up to the implementer of each new type so if you want, 702 you can count such references to the type object.) 703 */ 704 705 /* First define a pile of simple helper macros, one set per special 706 * build symbol. These either expand to the obvious things, or to 707 * nothing at all when the special mode isn't in effect. The main 708 * macros can later be defined just once then, yet expand to different 709 * things depending on which special build options are and aren't in effect. 710 * Trust me <wink>: while painful, this is 20x easier to understand than, 711 * e.g, defining _Py_NewReference five different times in a maze of nested 712 * #ifdefs (we used to do that -- it was impenetrable). 713 */ 714 #ifdef Py_REF_DEBUG 715 PyAPI_DATA(Py_ssize_t) _Py_RefTotal; 716 PyAPI_FUNC(void) _Py_NegativeRefcount(const char *fname, 717 int lineno, PyObject *op); 718 PyAPI_FUNC(Py_ssize_t) _Py_GetRefTotal(void); 719 #define _Py_INC_REFTOTAL _Py_RefTotal++ 720 #define _Py_DEC_REFTOTAL _Py_RefTotal-- 721 #define _Py_REF_DEBUG_COMMA , 722 #define _Py_CHECK_REFCNT(OP) \ 723 { if (((PyObject*)OP)->ob_refcnt < 0) \ 724 _Py_NegativeRefcount(__FILE__, __LINE__, \ 725 (PyObject *)(OP)); \ 726 } 727 /* Py_REF_DEBUG also controls the display of refcounts and memory block 728 * allocations at the interactive prompt and at interpreter shutdown 729 */ 730 PyAPI_FUNC(void) _PyDebug_PrintTotalRefs(void); 731 #define _PY_DEBUG_PRINT_TOTAL_REFS() _PyDebug_PrintTotalRefs() 732 #else 733 #define _Py_INC_REFTOTAL 734 #define _Py_DEC_REFTOTAL 735 #define _Py_REF_DEBUG_COMMA 736 #define _Py_CHECK_REFCNT(OP) /* a semicolon */; 737 #define _PY_DEBUG_PRINT_TOTAL_REFS() 738 #endif /* Py_REF_DEBUG */ 739 740 #ifdef COUNT_ALLOCS 741 PyAPI_FUNC(void) inc_count(PyTypeObject *); 742 PyAPI_FUNC(void) dec_count(PyTypeObject *); 743 #define _Py_INC_TPALLOCS(OP) inc_count(Py_TYPE(OP)) 744 #define _Py_INC_TPFREES(OP) dec_count(Py_TYPE(OP)) 745 #define _Py_DEC_TPFREES(OP) Py_TYPE(OP)->tp_frees-- 746 #define _Py_COUNT_ALLOCS_COMMA , 747 #else 748 #define _Py_INC_TPALLOCS(OP) 749 #define _Py_INC_TPFREES(OP) 750 #define _Py_DEC_TPFREES(OP) 751 #define _Py_COUNT_ALLOCS_COMMA 752 #endif /* COUNT_ALLOCS */ 753 754 #ifdef Py_TRACE_REFS 755 /* Py_TRACE_REFS is such major surgery that we call external routines. */ 756 PyAPI_FUNC(void) _Py_NewReference(PyObject *); 757 PyAPI_FUNC(void) _Py_ForgetReference(PyObject *); 758 PyAPI_FUNC(void) _Py_Dealloc(PyObject *); 759 PyAPI_FUNC(void) _Py_PrintReferences(FILE *); 760 PyAPI_FUNC(void) _Py_PrintReferenceAddresses(FILE *); 761 PyAPI_FUNC(void) _Py_AddToAllObjects(PyObject *, int force); 762 763 #else 764 /* Without Py_TRACE_REFS, there's little enough to do that we expand code 765 * inline. 766 */ 767 #define _Py_NewReference(op) ( \ 768 _Py_INC_TPALLOCS(op) _Py_COUNT_ALLOCS_COMMA \ 769 _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \ 770 Py_REFCNT(op) = 1) 771 772 #define _Py_ForgetReference(op) _Py_INC_TPFREES(op) 773 774 #ifdef Py_LIMITED_API 775 PyAPI_FUNC(void) _Py_Dealloc(PyObject *); 776 #else 777 #define _Py_Dealloc(op) ( \ 778 _Py_INC_TPFREES(op) _Py_COUNT_ALLOCS_COMMA \ 779 (*Py_TYPE(op)->tp_dealloc)((PyObject *)(op))) 780 #endif 781 #endif /* !Py_TRACE_REFS */ 782 783 #define Py_INCREF(op) ( \ 784 _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \ 785 ((PyObject *)(op))->ob_refcnt++) 786 787 #define Py_DECREF(op) \ 788 do { \ 789 PyObject *_py_decref_tmp = (PyObject *)(op); \ 790 if (_Py_DEC_REFTOTAL _Py_REF_DEBUG_COMMA \ 791 --(_py_decref_tmp)->ob_refcnt != 0) \ 792 _Py_CHECK_REFCNT(_py_decref_tmp) \ 793 else \ 794 _Py_Dealloc(_py_decref_tmp); \ 795 } while (0) 796 797 /* Safely decref `op` and set `op` to NULL, especially useful in tp_clear 798 * and tp_dealloc implementations. 799 * 800 * Note that "the obvious" code can be deadly: 801 * 802 * Py_XDECREF(op); 803 * op = NULL; 804 * 805 * Typically, `op` is something like self->containee, and `self` is done 806 * using its `containee` member. In the code sequence above, suppose 807 * `containee` is non-NULL with a refcount of 1. Its refcount falls to 808 * 0 on the first line, which can trigger an arbitrary amount of code, 809 * possibly including finalizers (like __del__ methods or weakref callbacks) 810 * coded in Python, which in turn can release the GIL and allow other threads 811 * to run, etc. Such code may even invoke methods of `self` again, or cause 812 * cyclic gc to trigger, but-- oops! --self->containee still points to the 813 * object being torn down, and it may be in an insane state while being torn 814 * down. This has in fact been a rich historic source of miserable (rare & 815 * hard-to-diagnose) segfaulting (and other) bugs. 816 * 817 * The safe way is: 818 * 819 * Py_CLEAR(op); 820 * 821 * That arranges to set `op` to NULL _before_ decref'ing, so that any code 822 * triggered as a side-effect of `op` getting torn down no longer believes 823 * `op` points to a valid object. 824 * 825 * There are cases where it's safe to use the naive code, but they're brittle. 826 * For example, if `op` points to a Python integer, you know that destroying 827 * one of those can't cause problems -- but in part that relies on that 828 * Python integers aren't currently weakly referencable. Best practice is 829 * to use Py_CLEAR() even if you can't think of a reason for why you need to. 830 */ 831 #define Py_CLEAR(op) \ 832 do { \ 833 PyObject *_py_tmp = (PyObject *)(op); \ 834 if (_py_tmp != NULL) { \ 835 (op) = NULL; \ 836 Py_DECREF(_py_tmp); \ 837 } \ 838 } while (0) 839 840 /* Macros to use in case the object pointer may be NULL: */ 841 #define Py_XINCREF(op) \ 842 do { \ 843 PyObject *_py_xincref_tmp = (PyObject *)(op); \ 844 if (_py_xincref_tmp != NULL) \ 845 Py_INCREF(_py_xincref_tmp); \ 846 } while (0) 847 848 #define Py_XDECREF(op) \ 849 do { \ 850 PyObject *_py_xdecref_tmp = (PyObject *)(op); \ 851 if (_py_xdecref_tmp != NULL) \ 852 Py_DECREF(_py_xdecref_tmp); \ 853 } while (0) 854 855 #ifndef Py_LIMITED_API 856 /* Safely decref `op` and set `op` to `op2`. 857 * 858 * As in case of Py_CLEAR "the obvious" code can be deadly: 859 * 860 * Py_DECREF(op); 861 * op = op2; 862 * 863 * The safe way is: 864 * 865 * Py_SETREF(op, op2); 866 * 867 * That arranges to set `op` to `op2` _before_ decref'ing, so that any code 868 * triggered as a side-effect of `op` getting torn down no longer believes 869 * `op` points to a valid object. 870 * 871 * Py_XSETREF is a variant of Py_SETREF that uses Py_XDECREF instead of 872 * Py_DECREF. 873 */ 874 875 #define Py_SETREF(op, op2) \ 876 do { \ 877 PyObject *_py_tmp = (PyObject *)(op); \ 878 (op) = (op2); \ 879 Py_DECREF(_py_tmp); \ 880 } while (0) 881 882 #define Py_XSETREF(op, op2) \ 883 do { \ 884 PyObject *_py_tmp = (PyObject *)(op); \ 885 (op) = (op2); \ 886 Py_XDECREF(_py_tmp); \ 887 } while (0) 888 889 #endif /* ifndef Py_LIMITED_API */ 890 891 /* 892 These are provided as conveniences to Python runtime embedders, so that 893 they can have object code that is not dependent on Python compilation flags. 894 */ 895 PyAPI_FUNC(void) Py_IncRef(PyObject *); 896 PyAPI_FUNC(void) Py_DecRef(PyObject *); 897 898 #ifndef Py_LIMITED_API 899 PyAPI_DATA(PyTypeObject) _PyNone_Type; 900 PyAPI_DATA(PyTypeObject) _PyNotImplemented_Type; 901 #endif /* !Py_LIMITED_API */ 902 903 /* 904 _Py_NoneStruct is an object of undefined type which can be used in contexts 905 where NULL (nil) is not suitable (since NULL often means 'error'). 906 907 Don't forget to apply Py_INCREF() when returning this value!!! 908 */ 909 PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */ 910 #define Py_None (&_Py_NoneStruct) 911 912 /* Macro for returning Py_None from a function */ 913 #define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None 914 915 /* 916 Py_NotImplemented is a singleton used to signal that an operation is 917 not implemented for a given type combination. 918 */ 919 PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */ 920 #define Py_NotImplemented (&_Py_NotImplementedStruct) 921 922 /* Macro for returning Py_NotImplemented from a function */ 923 #define Py_RETURN_NOTIMPLEMENTED \ 924 return Py_INCREF(Py_NotImplemented), Py_NotImplemented 925 926 /* Rich comparison opcodes */ 927 #define Py_LT 0 928 #define Py_LE 1 929 #define Py_EQ 2 930 #define Py_NE 3 931 #define Py_GT 4 932 #define Py_GE 5 933 934 #ifndef Py_LIMITED_API 935 /* Maps Py_LT to Py_GT, ..., Py_GE to Py_LE. 936 * Defined in object.c. 937 */ 938 PyAPI_DATA(int) _Py_SwappedOp[]; 939 #endif /* !Py_LIMITED_API */ 940 941 942 /* 943 More conventions 944 ================ 945 946 Argument Checking 947 ----------------- 948 949 Functions that take objects as arguments normally don't check for nil 950 arguments, but they do check the type of the argument, and return an 951 error if the function doesn't apply to the type. 952 953 Failure Modes 954 ------------- 955 956 Functions may fail for a variety of reasons, including running out of 957 memory. This is communicated to the caller in two ways: an error string 958 is set (see errors.h), and the function result differs: functions that 959 normally return a pointer return NULL for failure, functions returning 960 an integer return -1 (which could be a legal return value too!), and 961 other functions return 0 for success and -1 for failure. 962 Callers should always check for errors before using the result. If 963 an error was set, the caller must either explicitly clear it, or pass 964 the error on to its caller. 965 966 Reference Counts 967 ---------------- 968 969 It takes a while to get used to the proper usage of reference counts. 970 971 Functions that create an object set the reference count to 1; such new 972 objects must be stored somewhere or destroyed again with Py_DECREF(). 973 Some functions that 'store' objects, such as PyTuple_SetItem() and 974 PyList_SetItem(), 975 don't increment the reference count of the object, since the most 976 frequent use is to store a fresh object. Functions that 'retrieve' 977 objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also 978 don't increment 979 the reference count, since most frequently the object is only looked at 980 quickly. Thus, to retrieve an object and store it again, the caller 981 must call Py_INCREF() explicitly. 982 983 NOTE: functions that 'consume' a reference count, like 984 PyList_SetItem(), consume the reference even if the object wasn't 985 successfully stored, to simplify error handling. 986 987 It seems attractive to make other functions that take an object as 988 argument consume a reference count; however, this may quickly get 989 confusing (even the current practice is already confusing). Consider 990 it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at 991 times. 992 */ 993 994 995 /* Trashcan mechanism, thanks to Christian Tismer. 996 997 When deallocating a container object, it's possible to trigger an unbounded 998 chain of deallocations, as each Py_DECREF in turn drops the refcount on "the 999 next" object in the chain to 0. This can easily lead to stack faults, and 1000 especially in threads (which typically have less stack space to work with). 1001 1002 A container object that participates in cyclic gc can avoid this by 1003 bracketing the body of its tp_dealloc function with a pair of macros: 1004 1005 static void 1006 mytype_dealloc(mytype *p) 1007 { 1008 ... declarations go here ... 1009 1010 PyObject_GC_UnTrack(p); // must untrack first 1011 Py_TRASHCAN_SAFE_BEGIN(p) 1012 ... The body of the deallocator goes here, including all calls ... 1013 ... to Py_DECREF on contained objects. ... 1014 Py_TRASHCAN_SAFE_END(p) 1015 } 1016 1017 CAUTION: Never return from the middle of the body! If the body needs to 1018 "get out early", put a label immediately before the Py_TRASHCAN_SAFE_END 1019 call, and goto it. Else the call-depth counter (see below) will stay 1020 above 0 forever, and the trashcan will never get emptied. 1021 1022 How it works: The BEGIN macro increments a call-depth counter. So long 1023 as this counter is small, the body of the deallocator is run directly without 1024 further ado. But if the counter gets large, it instead adds p to a list of 1025 objects to be deallocated later, skips the body of the deallocator, and 1026 resumes execution after the END macro. The tp_dealloc routine then returns 1027 without deallocating anything (and so unbounded call-stack depth is avoided). 1028 1029 When the call stack finishes unwinding again, code generated by the END macro 1030 notices this, and calls another routine to deallocate all the objects that 1031 may have been added to the list of deferred deallocations. In effect, a 1032 chain of N deallocations is broken into N / PyTrash_UNWIND_LEVEL pieces, 1033 with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL. 1034 */ 1035 1036 #ifndef Py_LIMITED_API 1037 /* This is the old private API, invoked by the macros before 3.2.4. 1038 Kept for binary compatibility of extensions using the stable ABI. */ 1039 PyAPI_FUNC(void) _PyTrash_deposit_object(PyObject*); 1040 PyAPI_FUNC(void) _PyTrash_destroy_chain(void); 1041 PyAPI_DATA(int) _PyTrash_delete_nesting; 1042 PyAPI_DATA(PyObject *) _PyTrash_delete_later; 1043 #endif /* !Py_LIMITED_API */ 1044 1045 /* The new thread-safe private API, invoked by the macros below. */ 1046 PyAPI_FUNC(void) _PyTrash_thread_deposit_object(PyObject*); 1047 PyAPI_FUNC(void) _PyTrash_thread_destroy_chain(void); 1048 1049 #define PyTrash_UNWIND_LEVEL 50 1050 1051 #define Py_TRASHCAN_SAFE_BEGIN(op) \ 1052 do { \ 1053 PyThreadState *_tstate = PyThreadState_GET(); \ 1054 if (_tstate->trash_delete_nesting < PyTrash_UNWIND_LEVEL) { \ 1055 ++_tstate->trash_delete_nesting; 1056 /* The body of the deallocator is here. */ 1057 #define Py_TRASHCAN_SAFE_END(op) \ 1058 --_tstate->trash_delete_nesting; \ 1059 if (_tstate->trash_delete_later && _tstate->trash_delete_nesting <= 0) \ 1060 _PyTrash_thread_destroy_chain(); \ 1061 } \ 1062 else \ 1063 _PyTrash_thread_deposit_object((PyObject*)op); \ 1064 } while (0); 1065 1066 #ifndef Py_LIMITED_API 1067 PyAPI_FUNC(void) 1068 _PyDebugAllocatorStats(FILE *out, const char *block_name, int num_blocks, 1069 size_t sizeof_block); 1070 PyAPI_FUNC(void) 1071 _PyObject_DebugTypeStats(FILE *out); 1072 #endif /* ifndef Py_LIMITED_API */ 1073 1074 #ifdef __cplusplus 1075 } 1076 #endif 1077 #endif /* !Py_OBJECT_H */ 1078