Include/object.h

   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 #ifdef Py_TRACE_REFS
  65 /* Define pointers to support a doubly-linked list of all live heap objects. */
  66 #define _PyObject_HEAD_EXTRA            \
  67         struct _object *_ob_next;       \
  68         struct _object *_ob_prev;
  69
  70 #define _PyObject_EXTRA_INIT 0, 0,
  71
  72 #else
  73 #define _PyObject_HEAD_EXTRA
  74 #define _PyObject_EXTRA_INIT
  75 #endif
  76
  77 /* PyObject_HEAD defines the initial segment of every PyObject. */
  78 #define PyObject_HEAD                   \
  79         _PyObject_HEAD_EXTRA            \
  80         int ob_refcnt;                  \
  81         struct _typeobject *ob_type;
  82
  83 #define PyObject_HEAD_INIT(type)        \
  84         _PyObject_EXTRA_INIT            \
  85         1, type,
  86
  87 /* PyObject_VAR_HEAD defines the initial segment of all variable-size
  88  * container objects.  These end with a declaration of an array with 1
  89  * element, but enough space is malloc'ed so that the array actually
  90  * has room for ob_size elements.  Note that ob_size is an element count,
  91  * not necessarily a byte count.
  92  */
  93 #define PyObject_VAR_HEAD               \
  94         PyObject_HEAD                   \
  95         int ob_size; /* Number of items in variable part */
  96
  97 /* Nothing is actually declared to be a PyObject, but every pointer to
  98  * a Python object can be cast to a PyObject*.  This is inheritance built
  99  * by hand.  Similarly every pointer to a variable-size Python object can,
 100  * in addition, be cast to PyVarObject*.
 101  */
 102 typedef struct _object {
 103         PyObject_HEAD
 104 } PyObject;
 105
 106 typedef struct {
 107         PyObject_VAR_HEAD
 108 } PyVarObject;
 109
 110
 111 /*
 112 Type objects contain a string containing the type name (to help somewhat
 113 in debugging), the allocation parameters (see PyObject_New() and
 114 PyObject_NewVar()),
 115 and methods for accessing objects of the type.  Methods are optional, a
 116 nil pointer meaning that particular kind of access is not available for
 117 this type.  The Py_DECREF() macro uses the tp_dealloc method without
 118 checking for a nil pointer; it should always be implemented except if
 119 the implementation can guarantee that the reference count will never
 120 reach zero (e.g., for statically allocated type objects).
 121
 122 NB: the methods for certain type groups are now contained in separate
 123 method blocks.
 124 */
 125
 126 typedef PyObject * (*unaryfunc)(PyObject *);
 127 typedef PyObject * (*binaryfunc)(PyObject *, PyObject *);
 128 typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *);
 129 typedef int (*inquiry)(PyObject *);
 130 typedef int (*coercion)(PyObject **, PyObject **);
 131 typedef PyObject *(*intargfunc)(PyObject *, int);
 132 typedef PyObject *(*intintargfunc)(PyObject *, int, int);
 133 typedef int(*intobjargproc)(PyObject *, int, PyObject *);
 134 typedef int(*intintobjargproc)(PyObject *, int, int, PyObject *);
 135 typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *);
 136 typedef int (*getreadbufferproc)(PyObject *, int, void **);
 137 typedef int (*getwritebufferproc)(PyObject *, int, void **);
 138 typedef int (*getsegcountproc)(PyObject *, int *);
 139 typedef int (*getcharbufferproc)(PyObject *, int, const char **);
 140 typedef int (*objobjproc)(PyObject *, PyObject *);
 141 typedef int (*visitproc)(PyObject *, void *);
 142 typedef int (*traverseproc)(PyObject *, visitproc, void *);
 143
 144 typedef struct {
 145         /* For numbers without flag bit Py_TPFLAGS_CHECKTYPES set, all
 146            arguments are guaranteed to be of the object's type (modulo
 147            coercion hacks -- i.e. if the type's coercion function
 148            returns other types, then these are allowed as well).  Numbers that
 149            have the Py_TPFLAGS_CHECKTYPES flag bit set should check *both*
 150            arguments for proper type and implement the necessary conversions
 151            in the slot functions themselves. */
 152
 153         binaryfunc nb_add;
 154         binaryfunc nb_subtract;
 155         binaryfunc nb_multiply;
 156         binaryfunc nb_divide;
 157         binaryfunc nb_remainder;
 158         binaryfunc nb_divmod;
 159         ternaryfunc nb_power;
 160         unaryfunc nb_negative;
 161         unaryfunc nb_positive;
 162         unaryfunc nb_absolute;
 163         inquiry nb_nonzero;
 164         unaryfunc nb_invert;
 165         binaryfunc nb_lshift;
 166         binaryfunc nb_rshift;
 167         binaryfunc nb_and;
 168         binaryfunc nb_xor;
 169         binaryfunc nb_or;
 170         coercion nb_coerce;
 171         unaryfunc nb_int;
 172         unaryfunc nb_long;
 173         unaryfunc nb_float;
 174         unaryfunc nb_oct;
 175         unaryfunc nb_hex;
 176         /* Added in release 2.0 */
 177         binaryfunc nb_inplace_add;
 178         binaryfunc nb_inplace_subtract;
 179         binaryfunc nb_inplace_multiply;
 180         binaryfunc nb_inplace_divide;
 181         binaryfunc nb_inplace_remainder;
 182         ternaryfunc nb_inplace_power;
 183         binaryfunc nb_inplace_lshift;
 184         binaryfunc nb_inplace_rshift;
 185         binaryfunc nb_inplace_and;
 186         binaryfunc nb_inplace_xor;
 187         binaryfunc nb_inplace_or;
 188
 189         /* Added in release 2.2 */
 190         /* The following require the Py_TPFLAGS_HAVE_CLASS flag */
 191         binaryfunc nb_floor_divide;
 192         binaryfunc nb_true_divide;
 193         binaryfunc nb_inplace_floor_divide;
 194         binaryfunc nb_inplace_true_divide;
 195 } PyNumberMethods;
 196
 197 typedef struct {
 198         inquiry sq_length;
 199         binaryfunc sq_concat;
 200         intargfunc sq_repeat;
 201         intargfunc sq_item;
 202         intintargfunc sq_slice;
 203         intobjargproc sq_ass_item;
 204         intintobjargproc sq_ass_slice;
 205         objobjproc sq_contains;
 206         /* Added in release 2.0 */
 207         binaryfunc sq_inplace_concat;
 208         intargfunc sq_inplace_repeat;
 209 } PySequenceMethods;
 210
 211 typedef struct {
 212         inquiry mp_length;
 213         binaryfunc mp_subscript;
 214         objobjargproc mp_ass_subscript;
 215 } PyMappingMethods;
 216
 217 typedef struct {
 218         getreadbufferproc bf_getreadbuffer;
 219         getwritebufferproc bf_getwritebuffer;
 220         getsegcountproc bf_getsegcount;
 221         getcharbufferproc bf_getcharbuffer;
 222 } PyBufferProcs;
 223
 224
 225 typedef void (*freefunc)(void *);
 226 typedef void (*destructor)(PyObject *);
 227 typedef int (*printfunc)(PyObject *, FILE *, int);
 228 typedef PyObject *(*getattrfunc)(PyObject *, const char *);
 229 typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
 230 typedef int (*setattrfunc)(PyObject *, const char *, PyObject *);
 231 typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *);
 232 typedef int (*cmpfunc)(PyObject *, PyObject *);
 233 typedef PyObject *(*reprfunc)(PyObject *);
 234 typedef long (*hashfunc)(PyObject *);
 235 typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int);
 236 typedef PyObject *(*getiterfunc) (PyObject *);
 237 typedef PyObject *(*iternextfunc) (PyObject *);
 238 typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *);
 239 typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *);
 240 typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
 241 typedef PyObject *(*newfunc)(struct _typeobject *, PyObject *, PyObject *);
 242 typedef PyObject *(*allocfunc)(struct _typeobject *, int);
 243
 244 typedef struct _typeobject {
 245         PyObject_VAR_HEAD
 246         const char *tp_name; /* For printing, in format "<module>.<name>" */
 247         int tp_basicsize, tp_itemsize; /* For allocation */
 248
 249         /* Methods to implement standard operations */
 250
 251         destructor tp_dealloc;
 252         printfunc tp_print;
 253         getattrfunc tp_getattr;
 254         setattrfunc tp_setattr;
 255         cmpfunc tp_compare;
 256         reprfunc tp_repr;
 257
 258         /* Method suites for standard classes */
 259
 260         PyNumberMethods *tp_as_number;
 261         PySequenceMethods *tp_as_sequence;
 262         PyMappingMethods *tp_as_mapping;
 263
 264         /* More standard operations (here for binary compatibility) */
 265
 266         hashfunc tp_hash;
 267         ternaryfunc tp_call;
 268         reprfunc tp_str;
 269         getattrofunc tp_getattro;
 270         setattrofunc tp_setattro;
 271
 272         /* Functions to access object as input/output buffer */
 273         PyBufferProcs *tp_as_buffer;
 274
 275         /* Flags to define presence of optional/expanded features */
 276         long tp_flags;
 277
 278         const char *tp_doc; /* Documentation string */
 279
 280         /* Assigned meaning in release 2.0 */
 281         /* call function for all accessible objects */
 282         traverseproc tp_traverse;
 283
 284         /* delete references to contained objects */
 285         inquiry tp_clear;
 286
 287         /* Assigned meaning in release 2.1 */
 288         /* rich comparisons */
 289         richcmpfunc tp_richcompare;
 290
 291         /* weak reference enabler */
 292         long tp_weaklistoffset;
 293
 294         /* Added in release 2.2 */
 295         /* Iterators */
 296         getiterfunc tp_iter;
 297         iternextfunc tp_iternext;
 298
 299         /* Attribute descriptor and subclassing stuff */
 300         struct PyMethodDef *tp_methods;
 301         struct PyMemberDef *tp_members;
 302         struct PyGetSetDef *tp_getset;
 303         struct _typeobject *tp_base;
 304         PyObject *tp_dict;
 305         descrgetfunc tp_descr_get;
 306         descrsetfunc tp_descr_set;
 307         long tp_dictoffset;
 308         initproc tp_init;
 309         allocfunc tp_alloc;
 310         newfunc tp_new;
 311         freefunc tp_free; /* Low-level free-memory routine */
 312         inquiry tp_is_gc; /* For PyObject_IS_GC */
 313         PyObject *tp_bases;
 314         PyObject *tp_mro; /* method resolution order */
 315         PyObject *tp_cache;
 316         PyObject *tp_subclasses;
 317         PyObject *tp_weaklist;
 318         destructor tp_del;
 319
 320 #ifdef COUNT_ALLOCS
 321         /* these must be last and never explicitly initialized */
 322         int tp_allocs;
 323         int tp_frees;
 324         int tp_maxalloc;
 325         struct _typeobject *tp_next;
 326 #endif
 327 } PyTypeObject;
 328
 329
 330 /* The *real* layout of a type object when allocated on the heap */
 331 typedef struct _heaptypeobject {
 332         /* Note: there's a dependency on the order of these members
 333            in slotptr() in typeobject.c . */
 334         PyTypeObject type;
 335         PyNumberMethods as_number;
 336         PyMappingMethods as_mapping;
 337         PySequenceMethods as_sequence; /* as_sequence comes after as_mapping,
 338                                           so that the mapping wins when both
 339                                           the mapping and the sequence define
 340                                           a given operator (e.g. __getitem__).
 341                                           see add_operators() in typeobject.c . */
 342         PyBufferProcs as_buffer;
 343         PyObject *name, *slots;
 344         /* here are optional user slots, followed by the members. */
 345 } PyHeapTypeObject;
 346
 347 /* access macro to the members which are floating "behind" the object */
 348 #define PyHeapType_GET_MEMBERS(etype) \
 349     ((PyMemberDef *)(((char *)etype) + (etype)->type.ob_type->tp_basicsize))
 350
 351
 352 /* Generic type check */
 353 PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *);
 354 #define PyObject_TypeCheck(ob, tp) \
 355         ((ob)->ob_type == (tp) || PyType_IsSubtype((ob)->ob_type, (tp)))
 356
 357 PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */
 358 PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */
 359 PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */
 360
 361 #define PyType_Check(op) PyObject_TypeCheck(op, &PyType_Type)
 362 #define PyType_CheckExact(op) ((op)->ob_type == &PyType_Type)
 363
 364 PyAPI_FUNC(int) PyType_Ready(PyTypeObject *);
 365 PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, int);
 366 PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *,
 367                                                PyObject *, PyObject *);
 368 PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *);
 369
 370 /* Generic operations on objects */
 371 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int);
 372 PyAPI_FUNC(void) _PyObject_Dump(PyObject *);
 373 PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
 374 PyAPI_FUNC(PyObject *) _PyObject_Str(PyObject *);
 375 PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
 376 #ifdef Py_USING_UNICODE
 377 PyAPI_FUNC(PyObject *) PyObject_Unicode(PyObject *);
 378 #endif
 379 PyAPI_FUNC(int) PyObject_Compare(PyObject *, PyObject *);
 380 PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
 381 PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
 382 PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *);
 383 PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *);
 384 PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *);
 385 PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
 386 PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
 387 PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
 388 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *);
 389 PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *);
 390 PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
 391 PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *,
 392                                               PyObject *, PyObject *);
 393 PyAPI_FUNC(long) PyObject_Hash(PyObject *);
 394 PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
 395 PyAPI_FUNC(int) PyObject_Not(PyObject *);
 396 PyAPI_FUNC(int) PyCallable_Check(PyObject *);
 397 PyAPI_FUNC(int) PyNumber_Coerce(PyObject **, PyObject **);
 398 PyAPI_FUNC(int) PyNumber_CoerceEx(PyObject **, PyObject **);
 399
 400 PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
 401
 402 /* A slot function whose address we need to compare */
 403 extern int _PyObject_SlotCompare(PyObject *, PyObject *);
 404
 405
 406 /* PyObject_Dir(obj) acts like Python __builtin__.dir(obj), returning a
 407    list of strings.  PyObject_Dir(NULL) is like __builtin__.dir(),
 408    returning the names of the current locals.  In this case, if there are
 409    no current locals, NULL is returned, and PyErr_Occurred() is false.
 410 */
 411 PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
 412
 413
 414 /* Helpers for printing recursive container types */
 415 PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
 416 PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
 417
 418 /* Helpers for hash functions */
 419 PyAPI_FUNC(long) _Py_HashDouble(double);
 420 PyAPI_FUNC(long) _Py_HashPointer(void*);
 421
 422 /* Helper for passing objects to printf and the like */
 423 #define PyObject_REPR(obj) PyString_AS_STRING(PyObject_Repr(obj))
 424
 425 /* Flag bits for printing: */
 426 #define Py_PRINT_RAW    1       /* No string quotes etc. */
 427
 428 /*
 429 `Type flags (tp_flags)
 430
 431 These flags are used to extend the type structure in a backwards-compatible
 432 fashion. Extensions can use the flags to indicate (and test) when a given
 433 type structure contains a new feature. The Python core will use these when
 434 introducing new functionality between major revisions (to avoid mid-version
 435 changes in the PYTHON_API_VERSION).
 436
 437 Arbitration of the flag bit positions will need to be coordinated among
 438 all extension writers who publically release their extensions (this will
 439 be fewer than you might expect!)..
 440
 441 Python 1.5.2 introduced the bf_getcharbuffer slot into PyBufferProcs.
 442
 443 Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
 444
 445 Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
 446 given type object has a specified feature.
 447 */
 448
 449 /* PyBufferProcs contains bf_getcharbuffer */
 450 #define Py_TPFLAGS_HAVE_GETCHARBUFFER  (1L<<0)
 451
 452 /* PySequenceMethods contains sq_contains */
 453 #define Py_TPFLAGS_HAVE_SEQUENCE_IN (1L<<1)
 454
 455 /* This is here for backwards compatibility.  Extensions that use the old GC
 456  * API will still compile but the objects will not be tracked by the GC. */
 457 #define Py_TPFLAGS_GC 0 /* used to be (1L<<2) */
 458
 459 /* PySequenceMethods and PyNumberMethods contain in-place operators */
 460 #define Py_TPFLAGS_HAVE_INPLACEOPS (1L<<3)
 461
 462 /* PyNumberMethods do their own coercion */
 463 #define Py_TPFLAGS_CHECKTYPES (1L<<4)
 464
 465 /* tp_richcompare is defined */
 466 #define Py_TPFLAGS_HAVE_RICHCOMPARE (1L<<5)
 467
 468 /* Objects which are weakly referencable if their tp_weaklistoffset is >0 */
 469 #define Py_TPFLAGS_HAVE_WEAKREFS (1L<<6)
 470
 471 /* tp_iter is defined */
 472 #define Py_TPFLAGS_HAVE_ITER (1L<<7)
 473
 474 /* New members introduced by Python 2.2 exist */
 475 #define Py_TPFLAGS_HAVE_CLASS (1L<<8)
 476
 477 /* Set if the type object is dynamically allocated */
 478 #define Py_TPFLAGS_HEAPTYPE (1L<<9)
 479
 480 /* Set if the type allows subclassing */
 481 #define Py_TPFLAGS_BASETYPE (1L<<10)
 482
 483 /* Set if the type is 'ready' -- fully initialized */
 484 #define Py_TPFLAGS_READY (1L<<12)
 485
 486 /* Set while the type is being 'readied', to prevent recursive ready calls */
 487 #define Py_TPFLAGS_READYING (1L<<13)
 488
 489 /* Objects support garbage collection (see objimp.h) */
 490 #define Py_TPFLAGS_HAVE_GC (1L<<14)
 491
 492 /* These two bits are preserved for Stackless Python, next after this is 16 */
 493 #ifdef STACKLESS
 494 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3L<<15)
 495 #else
 496 #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
 497 #endif
 498
 499 #define Py_TPFLAGS_DEFAULT  ( \
 500                              Py_TPFLAGS_HAVE_GETCHARBUFFER | \
 501                              Py_TPFLAGS_HAVE_SEQUENCE_IN | \
 502                              Py_TPFLAGS_HAVE_INPLACEOPS | \
 503                              Py_TPFLAGS_HAVE_RICHCOMPARE | \
 504                              Py_TPFLAGS_HAVE_WEAKREFS | \
 505                              Py_TPFLAGS_HAVE_ITER | \
 506                              Py_TPFLAGS_HAVE_CLASS | \
 507                              Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
 508                             0)
 509
 510 #define PyType_HasFeature(t,f)  (((t)->tp_flags & (f)) != 0)
 511
 512
 513 /*
 514 The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
 515 reference counts.  Py_DECREF calls the object's deallocator function when
 516 the refcount falls to 0; for
 517 objects that don't contain references to other objects or heap memory
 518 this can be the standard function free().  Both macros can be used
 519 wherever a void expression is allowed.  The argument must not be a
 520 NIL pointer.  If it may be NIL, use Py_XINCREF/Py_XDECREF instead.
 521 The macro _Py_NewReference(op) initialize reference counts to 1, and
 522 in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
 523 bookkeeping appropriate to the special build.
 524
 525 We assume that the reference count field can never overflow; this can
 526 be proven when the size of the field is the same as the pointer size, so
 527 we ignore the possibility.  Provided a C int is at least 32 bits (which
 528 is implicitly assumed in many parts of this code), that's enough for
 529 about 2**31 references to an object.
 530
 531 XXX The following became out of date in Python 2.2, but I'm not sure
 532 XXX what the full truth is now.  Certainly, heap-allocated type objects
 533 XXX can and should be deallocated.
 534 Type objects should never be deallocated; the type pointer in an object
 535 is not considered to be a reference to the type object, to save
 536 complications in the deallocation function.  (This is actually a
 537 decision that's up to the implementer of each new type so if you want,
 538 you can count such references to the type object.)
 539
 540 *** WARNING*** The Py_DECREF macro must have a side-effect-free argument
 541 since it may evaluate its argument multiple times.  (The alternative
 542 would be to mace it a proper function or assign it to a global temporary
 543 variable first, both of which are slower; and in a multi-threaded
 544 environment the global variable trick is not safe.)
 545 */
 546
 547 /* First define a pile of simple helper macros, one set per special
 548  * build symbol.  These either expand to the obvious things, or to
 549  * nothing at all when the special mode isn't in effect.  The main
 550  * macros can later be defined just once then, yet expand to different
 551  * things depending on which special build options are and aren't in effect.
 552  * Trust me <wink>:  while painful, this is 20x easier to understand than,
 553  * e.g, defining _Py_NewReference five different times in a maze of nested
 554  * #ifdefs (we used to do that -- it was impenetrable).
 555  */
 556 #ifdef Py_REF_DEBUG
 557 PyAPI_DATA(long) _Py_RefTotal;
 558 PyAPI_FUNC(void) _Py_NegativeRefcount(const char *fname,
 559                                             int lineno, PyObject *op);
 560 #define _Py_INC_REFTOTAL        _Py_RefTotal++
 561 #define _Py_DEC_REFTOTAL        _Py_RefTotal--
 562 #define _Py_REF_DEBUG_COMMA     ,
 563 #define _Py_CHECK_REFCNT(OP)                                    \
 564 {       if ((OP)->ob_refcnt < 0)                                \
 565                 _Py_NegativeRefcount(__FILE__, __LINE__,        \
 566                                      (PyObject *)(OP));         \
 567 }
 568 #else
 569 #define _Py_INC_REFTOTAL
 570 #define _Py_DEC_REFTOTAL
 571 #define _Py_REF_DEBUG_COMMA
 572 #define _Py_CHECK_REFCNT(OP)    /* a semicolon */;
 573 #endif /* Py_REF_DEBUG */
 574
 575 #ifdef COUNT_ALLOCS
 576 PyAPI_FUNC(void) inc_count(PyTypeObject *);
 577 #define _Py_INC_TPALLOCS(OP)    inc_count((OP)->ob_type)
 578 #define _Py_INC_TPFREES(OP)     (OP)->ob_type->tp_frees++
 579 #define _Py_DEC_TPFREES(OP)     (OP)->ob_type->tp_frees--
 580 #define _Py_COUNT_ALLOCS_COMMA  ,
 581 #else
 582 #define _Py_INC_TPALLOCS(OP)
 583 #define _Py_INC_TPFREES(OP)
 584 #define _Py_DEC_TPFREES(OP)
 585 #define _Py_COUNT_ALLOCS_COMMA
 586 #endif /* COUNT_ALLOCS */
 587
 588 #ifdef Py_TRACE_REFS
 589 /* Py_TRACE_REFS is such major surgery that we call external routines. */
 590 PyAPI_FUNC(void) _Py_NewReference(PyObject *);
 591 PyAPI_FUNC(void) _Py_ForgetReference(PyObject *);
 592 PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
 593 PyAPI_FUNC(void) _Py_PrintReferences(FILE *);
 594 PyAPI_FUNC(void) _Py_PrintReferenceAddresses(FILE *);
 595 PyAPI_FUNC(void) _Py_AddToAllObjects(PyObject *, int force);
 596
 597 #else
 598 /* Without Py_TRACE_REFS, there's little enough to do that we expand code
 599  * inline.
 600  */
 601 #define _Py_NewReference(op) (                          \
 602         _Py_INC_TPALLOCS(op) _Py_COUNT_ALLOCS_COMMA     \
 603         _Py_INC_REFTOTAL  _Py_REF_DEBUG_COMMA           \
 604         (op)->ob_refcnt = 1)
 605
 606 #define _Py_ForgetReference(op) _Py_INC_TPFREES(op)
 607
 608 #define _Py_Dealloc(op) (                               \
 609         _Py_INC_TPFREES(op) _Py_COUNT_ALLOCS_COMMA      \
 610         (*(op)->ob_type->tp_dealloc)((PyObject *)(op)))
 611 #endif /* !Py_TRACE_REFS */
 612
 613 #define Py_INCREF(op) (                         \
 614         _Py_INC_REFTOTAL  _Py_REF_DEBUG_COMMA   \
 615         (op)->ob_refcnt++)
 616
 617 #define Py_DECREF(op)                                   \
 618         if (_Py_DEC_REFTOTAL  _Py_REF_DEBUG_COMMA       \
 619             --(op)->ob_refcnt != 0)                     \
 620                 _Py_CHECK_REFCNT(op)                    \
 621         else                                            \
 622                 _Py_Dealloc((PyObject *)(op))
 623
 624 #define Py_CLEAR(op)                            \
 625         do {                                    \
 626                 if (op) {                       \
 627                         PyObject *tmp = (PyObject *)(op);       \
 628                         (op) = NULL;            \
 629                         Py_DECREF(tmp);         \
 630                 }                               \
 631         } while (0)
 632
 633 /* Macros to use in case the object pointer may be NULL: */
 634 #define Py_XINCREF(op) if ((op) == NULL) ; else Py_INCREF(op)
 635 #define Py_XDECREF(op) if ((op) == NULL) ; else Py_DECREF(op)
 636
 637 /*
 638 These are provided as conveniences to Python runtime embedders, so that
 639 they can have object code that is not dependent on Python compilation flags.
 640 */
 641 PyAPI_FUNC(void) Py_IncRef(PyObject *);
 642 PyAPI_FUNC(void) Py_DecRef(PyObject *);
 643
 644 /*
 645 _Py_NoneStruct is an object of undefined type which can be used in contexts
 646 where NULL (nil) is not suitable (since NULL often means 'error').
 647
 648 Don't forget to apply Py_INCREF() when returning this value!!!
 649 */
 650 PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
 651 #define Py_None (&_Py_NoneStruct)
 652
 653 /* Macro for returning Py_None from a function */
 654 #define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None
 655
 656 /*
 657 Py_NotImplemented is a singleton used to signal that an operation is
 658 not implemented for a given type combination.
 659 */
 660 PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
 661 #define Py_NotImplemented (&_Py_NotImplementedStruct)
 662
 663 /* Rich comparison opcodes */
 664 #define Py_LT 0
 665 #define Py_LE 1
 666 #define Py_EQ 2
 667 #define Py_NE 3
 668 #define Py_GT 4
 669 #define Py_GE 5
 670
 671 /* Maps Py_LT to Py_GT, ..., Py_GE to Py_LE.
 672  * Defined in object.c.
 673  */
 674 PyAPI_DATA(int) _Py_SwappedOp[];
 675
 676 /*
 677 Define staticforward and statichere for source compatibility with old
 678 C extensions.
 679
 680 The staticforward define was needed to support certain broken C
 681 compilers (notably SCO ODT 3.0, perhaps early AIX as well) botched the
 682 static keyword when it was used with a forward declaration of a static
 683 initialized structure.  Standard C allows the forward declaration with
 684 static, and we've decided to stop catering to broken C compilers.
 685 (In fact, we expect that the compilers are all fixed eight years later.)
 686 */
 687
 688 #define staticforward static
 689 #define statichere static
 690
 691
 692 /*
 693 More conventions
 694 ================
 695
 696 Argument Checking
 697 -----------------
 698
 699 Functions that take objects as arguments normally don't check for nil
 700 arguments, but they do check the type of the argument, and return an
 701 error if the function doesn't apply to the type.
 702
 703 Failure Modes
 704 -------------
 705
 706 Functions may fail for a variety of reasons, including running out of
 707 memory.  This is communicated to the caller in two ways: an error string
 708 is set (see errors.h), and the function result differs: functions that
 709 normally return a pointer return NULL for failure, functions returning
 710 an integer return -1 (which could be a legal return value too!), and
 711 other functions return 0 for success and -1 for failure.
 712 Callers should always check for errors before using the result.  If
 713 an error was set, the caller must either explicitly clear it, or pass
 714 the error on to its caller.
 715
 716 Reference Counts
 717 ----------------
 718
 719 It takes a while to get used to the proper usage of reference counts.
 720
 721 Functions that create an object set the reference count to 1; such new
 722 objects must be stored somewhere or destroyed again with Py_DECREF().
 723 Some functions that 'store' objects, such as PyTuple_SetItem() and
 724 PyList_SetItem(),
 725 don't increment the reference count of the object, since the most
 726 frequent use is to store a fresh object.  Functions that 'retrieve'
 727 objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
 728 don't increment
 729 the reference count, since most frequently the object is only looked at
 730 quickly.  Thus, to retrieve an object and store it again, the caller
 731 must call Py_INCREF() explicitly.
 732
 733 NOTE: functions that 'consume' a reference count, like
 734 PyList_SetItem(), consume the reference even if the object wasn't
 735 successfully stored, to simplify error handling.
 736
 737 It seems attractive to make other functions that take an object as
 738 argument consume a reference count; however, this may quickly get
 739 confusing (even the current practice is already confusing).  Consider
 740 it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
 741 times.
 742 */
 743
 744
 745 /* Trashcan mechanism, thanks to Christian Tismer.
 746
 747 When deallocating a container object, it's possible to trigger an unbounded
 748 chain of deallocations, as each Py_DECREF in turn drops the refcount on "the
 749 next" object in the chain to 0.  This can easily lead to stack faults, and
 750 especially in threads (which typically have less stack space to work with).
 751
 752 A container object that participates in cyclic gc can avoid this by
 753 bracketing the body of its tp_dealloc function with a pair of macros:
 754
 755 static void
 756 mytype_dealloc(mytype *p)
 757 {
 758         ... declarations go here ...
 759
 760         PyObject_GC_UnTrack(p);    // must untrack first
 761         Py_TRASHCAN_SAFE_BEGIN(p)
 762         ... The body of the deallocator goes here, including all calls ...
 763         ... to Py_DECREF on contained objects.                         ...
 764         Py_TRASHCAN_SAFE_END(p)
 765 }
 766
 767 CAUTION:  Never return from the middle of the body!  If the body needs to
 768 "get out early", put a label immediately before the Py_TRASHCAN_SAFE_END
 769 call, and goto it.  Else the call-depth counter (see below) will stay
 770 above 0 forever, and the trashcan will never get emptied.
 771
 772 How it works:  The BEGIN macro increments a call-depth counter.  So long
 773 as this counter is small, the body of the deallocator is run directly without
 774 further ado.  But if the counter gets large, it instead adds p to a list of
 775 objects to be deallocated later, skips the body of the deallocator, and
 776 resumes execution after the END macro.  The tp_dealloc routine then returns
 777 without deallocating anything (and so unbounded call-stack depth is avoided).
 778
 779 When the call stack finishes unwinding again, code generated by the END macro
 780 notices this, and calls another routine to deallocate all the objects that
 781 may have been added to the list of deferred deallocations.  In effect, a
 782 chain of N deallocations is broken into N / PyTrash_UNWIND_LEVEL pieces,
 783 with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL.
 784 */
 785
 786 PyAPI_FUNC(void) _PyTrash_deposit_object(PyObject*);
 787 PyAPI_FUNC(void) _PyTrash_destroy_chain(void);
 788 PyAPI_DATA(int) _PyTrash_delete_nesting;
 789 PyAPI_DATA(PyObject *) _PyTrash_delete_later;
 790
 791 #define PyTrash_UNWIND_LEVEL 50
 792
 793 #define Py_TRASHCAN_SAFE_BEGIN(op) \
 794         if (_PyTrash_delete_nesting < PyTrash_UNWIND_LEVEL) { \
 795                 ++_PyTrash_delete_nesting;
 796                 /* The body of the deallocator is here. */
 797 #define Py_TRASHCAN_SAFE_END(op) \
 798                 --_PyTrash_delete_nesting; \
 799                 if (_PyTrash_delete_later && _PyTrash_delete_nesting <= 0) \
 800                         _PyTrash_destroy_chain(); \
 801         } \
 802         else \
 803                 _PyTrash_deposit_object((PyObject*)op);
 804
 805 #ifdef __cplusplus
 806 }
 807 #endif
 808 #endif /* !Py_OBJECT_H */