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