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 *, char *);
 229 typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
 230 typedef int (*setattrfunc)(PyObject *, 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         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         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 #ifdef Py_USING_UNICODE
 376 PyAPI_FUNC(PyObject *) PyObject_Unicode(PyObject *);
 377 #endif
 378 PyAPI_FUNC(int) PyObject_Compare(PyObject *, PyObject *);
 379 PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
 380 PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
 381 PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, char *);
 382 PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, char *, PyObject *);
 383 PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, char *);
 384 PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
 385 PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
 386 PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
 387 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *);
 388 PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
 389 PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *,
 390                                               PyObject *, PyObject *);
 391 PyAPI_FUNC(long) PyObject_Hash(PyObject *);
 392 PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
 393 PyAPI_FUNC(int) PyObject_Not(PyObject *);
 394 PyAPI_FUNC(int) PyCallable_Check(PyObject *);
 395 PyAPI_FUNC(int) PyNumber_Coerce(PyObject **, PyObject **);
 396 PyAPI_FUNC(int) PyNumber_CoerceEx(PyObject **, PyObject **);
 397
 398 PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
 399
 400 /* A slot function whose address we need to compare */
 401 extern int _PyObject_SlotCompare(PyObject *, PyObject *);
 402
 403
 404 /* PyObject_Dir(obj) acts like Python __builtin__.dir(obj), returning a
 405    list of strings.  PyObject_Dir(NULL) is like __builtin__.dir(),
 406    returning the names of the current locals.  In this case, if there are
 407    no current locals, NULL is returned, and PyErr_Occurred() is false.
 408 */
 409 PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
 410
 411
 412 /* Helpers for printing recursive container types */
 413 PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
 414 PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
 415
 416 /* Helpers for hash functions */
 417 PyAPI_FUNC(long) _Py_HashDouble(double);
 418 PyAPI_FUNC(long) _Py_HashPointer(void*);
 419
 420 /* Helper for passing objects to printf and the like */
 421 #define PyObject_REPR(obj) PyString_AS_STRING(PyObject_Repr(obj))
 422
 423 /* Flag bits for printing: */
 424 #define Py_PRINT_RAW    1       /* No string quotes etc. */
 425
 426 /*
 427 `Type flags (tp_flags)
 428
 429 These flags are used to extend the type structure in a backwards-compatible
 430 fashion. Extensions can use the flags to indicate (and test) when a given
 431 type structure contains a new feature. The Python core will use these when
 432 introducing new functionality between major revisions (to avoid mid-version
 433 changes in the PYTHON_API_VERSION).
 434
 435 Arbitration of the flag bit positions will need to be coordinated among
 436 all extension writers who publically release their extensions (this will
 437 be fewer than you might expect!)..
 438
 439 Python 1.5.2 introduced the bf_getcharbuffer slot into PyBufferProcs.
 440
 441 Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
 442
 443 Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
 444 given type object has a specified feature.
 445 */
 446
 447 /* PyBufferProcs contains bf_getcharbuffer */
 448 #define Py_TPFLAGS_HAVE_GETCHARBUFFER  (1L<<0)
 449
 450 /* PySequenceMethods contains sq_contains */
 451 #define Py_TPFLAGS_HAVE_SEQUENCE_IN (1L<<1)
 452
 453 /* This is here for backwards compatibility.  Extensions that use the old GC
 454  * API will still compile but the objects will not be tracked by the GC. */
 455 #define Py_TPFLAGS_GC 0 /* used to be (1L<<2) */
 456
 457 /* PySequenceMethods and PyNumberMethods contain in-place operators */
 458 #define Py_TPFLAGS_HAVE_INPLACEOPS (1L<<3)
 459
 460 /* PyNumberMethods do their own coercion */
 461 #define Py_TPFLAGS_CHECKTYPES (1L<<4)
 462
 463 /* tp_richcompare is defined */
 464 #define Py_TPFLAGS_HAVE_RICHCOMPARE (1L<<5)
 465
 466 /* Objects which are weakly referencable if their tp_weaklistoffset is >0 */
 467 #define Py_TPFLAGS_HAVE_WEAKREFS (1L<<6)
 468
 469 /* tp_iter is defined */
 470 #define Py_TPFLAGS_HAVE_ITER (1L<<7)
 471
 472 /* New members introduced by Python 2.2 exist */
 473 #define Py_TPFLAGS_HAVE_CLASS (1L<<8)
 474
 475 /* Set if the type object is dynamically allocated */
 476 #define Py_TPFLAGS_HEAPTYPE (1L<<9)
 477
 478 /* Set if the type allows subclassing */
 479 #define Py_TPFLAGS_BASETYPE (1L<<10)
 480
 481 /* Set if the type is 'ready' -- fully initialized */
 482 #define Py_TPFLAGS_READY (1L<<12)
 483
 484 /* Set while the type is being 'readied', to prevent recursive ready calls */
 485 #define Py_TPFLAGS_READYING (1L<<13)
 486
 487 /* Objects support garbage collection (see objimp.h) */
 488 #define Py_TPFLAGS_HAVE_GC (1L<<14)
 489
 490 #define Py_TPFLAGS_DEFAULT  ( \
 491                              Py_TPFLAGS_HAVE_GETCHARBUFFER | \
 492                              Py_TPFLAGS_HAVE_SEQUENCE_IN | \
 493                              Py_TPFLAGS_HAVE_INPLACEOPS | \
 494                              Py_TPFLAGS_HAVE_RICHCOMPARE | \
 495                              Py_TPFLAGS_HAVE_WEAKREFS | \
 496                              Py_TPFLAGS_HAVE_ITER | \
 497                              Py_TPFLAGS_HAVE_CLASS | \
 498                             0)
 499
 500 #define PyType_HasFeature(t,f)  (((t)->tp_flags & (f)) != 0)
 501
 502
 503 /*
 504 The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
 505 reference counts.  Py_DECREF calls the object's deallocator function when
 506 the refcount falls to 0; for
 507 objects that don't contain references to other objects or heap memory
 508 this can be the standard function free().  Both macros can be used
 509 wherever a void expression is allowed.  The argument must not be a
 510 NIL pointer.  If it may be NIL, use Py_XINCREF/Py_XDECREF instead.
 511 The macro _Py_NewReference(op) initialize reference counts to 1, and
 512 in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
 513 bookkeeping appropriate to the special build.
 514
 515 We assume that the reference count field can never overflow; this can
 516 be proven when the size of the field is the same as the pointer size, so
 517 we ignore the possibility.  Provided a C int is at least 32 bits (which
 518 is implicitly assumed in many parts of this code), that's enough for
 519 about 2**31 references to an object.
 520
 521 XXX The following became out of date in Python 2.2, but I'm not sure
 522 XXX what the full truth is now.  Certainly, heap-allocated type objects
 523 XXX can and should be deallocated.
 524 Type objects should never be deallocated; the type pointer in an object
 525 is not considered to be a reference to the type object, to save
 526 complications in the deallocation function.  (This is actually a
 527 decision that's up to the implementer of each new type so if you want,
 528 you can count such references to the type object.)
 529
 530 *** WARNING*** The Py_DECREF macro must have a side-effect-free argument
 531 since it may evaluate its argument multiple times.  (The alternative
 532 would be to mace it a proper function or assign it to a global temporary
 533 variable first, both of which are slower; and in a multi-threaded
 534 environment the global variable trick is not safe.)
 535 */
 536
 537 /* First define a pile of simple helper macros, one set per special
 538  * build symbol.  These either expand to the obvious things, or to
 539  * nothing at all when the special mode isn't in effect.  The main
 540  * macros can later be defined just once then, yet expand to different
 541  * things depending on which special build options are and aren't in effect.
 542  * Trust me <wink>:  while painful, this is 20x easier to understand than,
 543  * e.g, defining _Py_NewReference five different times in a maze of nested
 544  * #ifdefs (we used to do that -- it was impenetrable).
 545  */
 546 #ifdef Py_REF_DEBUG
 547 PyAPI_DATA(long) _Py_RefTotal;
 548 PyAPI_FUNC(void) _Py_NegativeRefcount(const char *fname,
 549                                             int lineno, PyObject *op);
 550 #define _Py_INC_REFTOTAL        _Py_RefTotal++
 551 #define _Py_DEC_REFTOTAL        _Py_RefTotal--
 552 #define _Py_REF_DEBUG_COMMA     ,
 553 #define _Py_CHECK_REFCNT(OP)                                    \
 554 {       if ((OP)->ob_refcnt < 0)                                \
 555                 _Py_NegativeRefcount(__FILE__, __LINE__,        \
 556                                      (PyObject *)(OP));         \
 557 }
 558 #else
 559 #define _Py_INC_REFTOTAL
 560 #define _Py_DEC_REFTOTAL
 561 #define _Py_REF_DEBUG_COMMA
 562 #define _Py_CHECK_REFCNT(OP)    /* a semicolon */;
 563 #endif /* Py_REF_DEBUG */
 564
 565 #ifdef COUNT_ALLOCS
 566 PyAPI_FUNC(void) inc_count(PyTypeObject *);
 567 #define _Py_INC_TPALLOCS(OP)    inc_count((OP)->ob_type)
 568 #define _Py_INC_TPFREES(OP)     (OP)->ob_type->tp_frees++
 569 #define _Py_DEC_TPFREES(OP)     (OP)->ob_type->tp_frees--
 570 #define _Py_COUNT_ALLOCS_COMMA  ,
 571 #else
 572 #define _Py_INC_TPALLOCS(OP)
 573 #define _Py_INC_TPFREES(OP)
 574 #define _Py_DEC_TPFREES(OP)
 575 #define _Py_COUNT_ALLOCS_COMMA
 576 #endif /* COUNT_ALLOCS */
 577
 578 #ifdef Py_TRACE_REFS
 579 /* Py_TRACE_REFS is such major surgery that we call external routines. */
 580 PyAPI_FUNC(void) _Py_NewReference(PyObject *);
 581 PyAPI_FUNC(void) _Py_ForgetReference(PyObject *);
 582 PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
 583 PyAPI_FUNC(void) _Py_PrintReferences(FILE *);
 584
 585 #else
 586 /* Without Py_TRACE_REFS, there's little enough to do that we expand code
 587  * inline.
 588  */
 589 #define _Py_NewReference(op) (                          \
 590         _Py_INC_TPALLOCS(op) _Py_COUNT_ALLOCS_COMMA     \
 591         _Py_INC_REFTOTAL  _Py_REF_DEBUG_COMMA           \
 592         (op)->ob_refcnt = 1)
 593
 594 #define _Py_ForgetReference(op) _Py_INC_TPFREES(op)
 595
 596 #define _Py_Dealloc(op) (                               \
 597         _Py_INC_TPFREES(op) _Py_COUNT_ALLOCS_COMMA      \
 598         (*(op)->ob_type->tp_dealloc)((PyObject *)(op)))
 599 #endif /* !Py_TRACE_REFS */
 600
 601 #define Py_INCREF(op) (                         \
 602         _Py_INC_REFTOTAL  _Py_REF_DEBUG_COMMA   \
 603         (op)->ob_refcnt++)
 604
 605 #define Py_DECREF(op)                                   \
 606         if (_Py_DEC_REFTOTAL  _Py_REF_DEBUG_COMMA       \
 607             --(op)->ob_refcnt != 0)                     \
 608                 _Py_CHECK_REFCNT(op)                    \
 609         else                                            \
 610                 _Py_Dealloc((PyObject *)(op))
 611
 612 /* Macros to use in case the object pointer may be NULL: */
 613 #define Py_XINCREF(op) if ((op) == NULL) ; else Py_INCREF(op)
 614 #define Py_XDECREF(op) if ((op) == NULL) ; else Py_DECREF(op)
 615
 616 /*
 617 _Py_NoneStruct is an object of undefined type which can be used in contexts
 618 where NULL (nil) is not suitable (since NULL often means 'error').
 619
 620 Don't forget to apply Py_INCREF() when returning this value!!!
 621 */
 622 PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
 623 #define Py_None (&_Py_NoneStruct)
 624
 625 /*
 626 Py_NotImplemented is a singleton used to signal that an operation is
 627 not implemented for a given type combination.
 628 */
 629 PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
 630 #define Py_NotImplemented (&_Py_NotImplementedStruct)
 631
 632 /* Rich comparison opcodes */
 633 #define Py_LT 0
 634 #define Py_LE 1
 635 #define Py_EQ 2
 636 #define Py_NE 3
 637 #define Py_GT 4
 638 #define Py_GE 5
 639
 640 /*
 641 Define staticforward and statichere for source compatibility with old
 642 C extensions.
 643
 644 The staticforward define was needed to support certain broken C
 645 compilers (notably SCO ODT 3.0, perhaps early AIX as well) botched the
 646 static keyword when it was used with a forward declaration of a static
 647 initialized structure.  Standard C allows the forward declaration with
 648 static, and we've decided to stop catering to broken C compilers.
 649 (In fact, we expect that the compilers are all fixed eight years later.)
 650 */
 651
 652 #define staticforward static
 653 #define statichere static
 654
 655
 656 /*
 657 More conventions
 658 ================
 659
 660 Argument Checking
 661 -----------------
 662
 663 Functions that take objects as arguments normally don't check for nil
 664 arguments, but they do check the type of the argument, and return an
 665 error if the function doesn't apply to the type.
 666
 667 Failure Modes
 668 -------------
 669
 670 Functions may fail for a variety of reasons, including running out of
 671 memory.  This is communicated to the caller in two ways: an error string
 672 is set (see errors.h), and the function result differs: functions that
 673 normally return a pointer return NULL for failure, functions returning
 674 an integer return -1 (which could be a legal return value too!), and
 675 other functions return 0 for success and -1 for failure.
 676 Callers should always check for errors before using the result.  If
 677 an error was set, the caller must either explicitly clear it, or pass
 678 the error on to its caller.
 679
 680 Reference Counts
 681 ----------------
 682
 683 It takes a while to get used to the proper usage of reference counts.
 684
 685 Functions that create an object set the reference count to 1; such new
 686 objects must be stored somewhere or destroyed again with Py_DECREF().
 687 Functions that 'store' objects such as PyTuple_SetItem() and
 688 PyDict_SetItemString()
 689 don't increment the reference count of the object, since the most
 690 frequent use is to store a fresh object.  Functions that 'retrieve'
 691 objects such as PyTuple_GetItem() and PyDict_GetItemString() also
 692 don't increment
 693 the reference count, since most frequently the object is only looked at
 694 quickly.  Thus, to retrieve an object and store it again, the caller
 695 must call Py_INCREF() explicitly.
 696
 697 NOTE: functions that 'consume' a reference count like
 698 PyList_SetItemString() even consume the reference if the object wasn't
 699 stored, to simplify error handling.
 700
 701 It seems attractive to make other functions that take an object as
 702 argument consume a reference count; however this may quickly get
 703 confusing (even the current practice is already confusing).  Consider
 704 it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
 705 times.
 706 */
 707
 708
 709 /* Trashcan mechanism, thanks to Christian Tismer.
 710
 711 When deallocating a container object, it's possible to trigger an unbounded
 712 chain of deallocations, as each Py_DECREF in turn drops the refcount on "the
 713 next" object in the chain to 0.  This can easily lead to stack faults, and
 714 especially in threads (which typically have less stack space to work with).
 715
 716 A container object that participates in cyclic gc can avoid this by
 717 bracketing the body of its tp_dealloc function with a pair of macros:
 718
 719 static void
 720 mytype_dealloc(mytype *p)
 721 {
 722         ... declarations go here ...
 723
 724         PyObject_GC_UnTrack(p);    // must untrack first
 725         Py_TRASHCAN_SAFE_BEGIN(p)
 726         ... The body of the deallocator goes here, including all calls ...
 727         ... to Py_DECREF on contained objects.                         ...
 728         Py_TRASHCAN_SAFE_END(p)
 729 }
 730
 731 CAUTION:  Never return from the middle of the body!  If the body needs to
 732 "get out early", put a label immediately before the Py_TRASHCAN_SAFE_END
 733 call, and goto it.  Else the call-depth counter (see below) will stay
 734 above 0 forever, and the trashcan will never get emptied.
 735
 736 How it works:  The BEGIN macro increments a call-depth counter.  So long
 737 as this counter is small, the body of the deallocator is run directly without
 738 further ado.  But if the counter gets large, it instead adds p to a list of
 739 objects to be deallocated later, skips the body of the deallocator, and
 740 resumes execution after the END macro.  The tp_dealloc routine then returns
 741 without deallocating anything (and so unbounded call-stack depth is avoided).
 742
 743 When the call stack finishes unwinding again, code generated by the END macro
 744 notices this, and calls another routine to deallocate all the objects that
 745 may have been added to the list of deferred deallocations.  In effect, a
 746 chain of N deallocations is broken into N / PyTrash_UNWIND_LEVEL pieces,
 747 with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL.
 748 */
 749
 750 PyAPI_FUNC(void) _PyTrash_deposit_object(PyObject*);
 751 PyAPI_FUNC(void) _PyTrash_destroy_chain(void);
 752 PyAPI_DATA(int) _PyTrash_delete_nesting;
 753 PyAPI_DATA(PyObject *) _PyTrash_delete_later;
 754
 755 #define PyTrash_UNWIND_LEVEL 50
 756
 757 #define Py_TRASHCAN_SAFE_BEGIN(op) \
 758         if (_PyTrash_delete_nesting < PyTrash_UNWIND_LEVEL) { \
 759                 ++_PyTrash_delete_nesting;
 760                 /* The body of the deallocator is here. */
 761 #define Py_TRASHCAN_SAFE_END(op) \
 762                 --_PyTrash_delete_nesting; \
 763                 if (_PyTrash_delete_later && _PyTrash_delete_nesting <= 0) \
 764                         _PyTrash_destroy_chain(); \
 765         } \
 766         else \
 767                 _PyTrash_deposit_object((PyObject*)op);
 768
 769 #ifdef __cplusplus
 770 }
 771 #endif
 772 #endif /* !Py_OBJECT_H */