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 	unaryfunc 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 */