Chris@87: #ifndef Py_OBJECT_H Chris@87: #define Py_OBJECT_H Chris@87: #ifdef __cplusplus Chris@87: extern "C" { Chris@87: #endif Chris@87: Chris@87: Chris@87: /* Object and type object interface */ Chris@87: Chris@87: /* Chris@87: Objects are structures allocated on the heap. Special rules apply to Chris@87: the use of objects to ensure they are properly garbage-collected. Chris@87: Objects are never allocated statically or on the stack; they must be Chris@87: accessed through special macros and functions only. (Type objects are Chris@87: exceptions to the first rule; the standard types are represented by Chris@87: statically initialized type objects, although work on type/class unification Chris@87: for Python 2.2 made it possible to have heap-allocated type objects too). Chris@87: Chris@87: An object has a 'reference count' that is increased or decreased when a Chris@87: pointer to the object is copied or deleted; when the reference count Chris@87: reaches zero there are no references to the object left and it can be Chris@87: removed from the heap. Chris@87: Chris@87: An object has a 'type' that determines what it represents and what kind Chris@87: of data it contains. An object's type is fixed when it is created. Chris@87: Types themselves are represented as objects; an object contains a Chris@87: pointer to the corresponding type object. The type itself has a type Chris@87: pointer pointing to the object representing the type 'type', which Chris@87: contains a pointer to itself!). Chris@87: Chris@87: Objects do not float around in memory; once allocated an object keeps Chris@87: the same size and address. Objects that must hold variable-size data Chris@87: can contain pointers to variable-size parts of the object. Not all Chris@87: objects of the same type have the same size; but the size cannot change Chris@87: after allocation. (These restrictions are made so a reference to an Chris@87: object can be simply a pointer -- moving an object would require Chris@87: updating all the pointers, and changing an object's size would require Chris@87: moving it if there was another object right next to it.) Chris@87: Chris@87: Objects are always accessed through pointers of the type 'PyObject *'. Chris@87: The type 'PyObject' is a structure that only contains the reference count Chris@87: and the type pointer. The actual memory allocated for an object Chris@87: contains other data that can only be accessed after casting the pointer Chris@87: to a pointer to a longer structure type. This longer type must start Chris@87: with the reference count and type fields; the macro PyObject_HEAD should be Chris@87: used for this (to accommodate for future changes). The implementation Chris@87: of a particular object type can cast the object pointer to the proper Chris@87: type and back. Chris@87: Chris@87: A standard interface exists for objects that contain an array of items Chris@87: whose size is determined when the object is allocated. Chris@87: */ Chris@87: Chris@87: /* Py_DEBUG implies Py_TRACE_REFS. */ Chris@87: #if defined(Py_DEBUG) && !defined(Py_TRACE_REFS) Chris@87: #define Py_TRACE_REFS Chris@87: #endif Chris@87: Chris@87: /* Py_TRACE_REFS implies Py_REF_DEBUG. */ Chris@87: #if defined(Py_TRACE_REFS) && !defined(Py_REF_DEBUG) Chris@87: #define Py_REF_DEBUG Chris@87: #endif Chris@87: Chris@87: #ifdef Py_TRACE_REFS Chris@87: /* Define pointers to support a doubly-linked list of all live heap objects. */ Chris@87: #define _PyObject_HEAD_EXTRA \ Chris@87: struct _object *_ob_next; \ Chris@87: struct _object *_ob_prev; Chris@87: Chris@87: #define _PyObject_EXTRA_INIT 0, 0, Chris@87: Chris@87: #else Chris@87: #define _PyObject_HEAD_EXTRA Chris@87: #define _PyObject_EXTRA_INIT Chris@87: #endif Chris@87: Chris@87: /* PyObject_HEAD defines the initial segment of every PyObject. */ Chris@87: #define PyObject_HEAD \ Chris@87: _PyObject_HEAD_EXTRA \ Chris@87: Py_ssize_t ob_refcnt; \ Chris@87: struct _typeobject *ob_type; Chris@87: Chris@87: #define PyObject_HEAD_INIT(type) \ Chris@87: _PyObject_EXTRA_INIT \ Chris@87: 1, type, Chris@87: Chris@87: #define PyVarObject_HEAD_INIT(type, size) \ Chris@87: PyObject_HEAD_INIT(type) size, Chris@87: Chris@87: /* PyObject_VAR_HEAD defines the initial segment of all variable-size Chris@87: * container objects. These end with a declaration of an array with 1 Chris@87: * element, but enough space is malloc'ed so that the array actually Chris@87: * has room for ob_size elements. Note that ob_size is an element count, Chris@87: * not necessarily a byte count. Chris@87: */ Chris@87: #define PyObject_VAR_HEAD \ Chris@87: PyObject_HEAD \ Chris@87: Py_ssize_t ob_size; /* Number of items in variable part */ Chris@87: #define Py_INVALID_SIZE (Py_ssize_t)-1 Chris@87: Chris@87: /* Nothing is actually declared to be a PyObject, but every pointer to Chris@87: * a Python object can be cast to a PyObject*. This is inheritance built Chris@87: * by hand. Similarly every pointer to a variable-size Python object can, Chris@87: * in addition, be cast to PyVarObject*. Chris@87: */ Chris@87: typedef struct _object { Chris@87: PyObject_HEAD Chris@87: } PyObject; Chris@87: Chris@87: typedef struct { Chris@87: PyObject_VAR_HEAD Chris@87: } PyVarObject; Chris@87: Chris@87: #define Py_REFCNT(ob) (((PyObject*)(ob))->ob_refcnt) Chris@87: #define Py_TYPE(ob) (((PyObject*)(ob))->ob_type) Chris@87: #define Py_SIZE(ob) (((PyVarObject*)(ob))->ob_size) Chris@87: Chris@87: /* Chris@87: Type objects contain a string containing the type name (to help somewhat Chris@87: in debugging), the allocation parameters (see PyObject_New() and Chris@87: PyObject_NewVar()), Chris@87: and methods for accessing objects of the type. Methods are optional, a Chris@87: nil pointer meaning that particular kind of access is not available for Chris@87: this type. The Py_DECREF() macro uses the tp_dealloc method without Chris@87: checking for a nil pointer; it should always be implemented except if Chris@87: the implementation can guarantee that the reference count will never Chris@87: reach zero (e.g., for statically allocated type objects). Chris@87: Chris@87: NB: the methods for certain type groups are now contained in separate Chris@87: method blocks. Chris@87: */ Chris@87: Chris@87: typedef PyObject * (*unaryfunc)(PyObject *); Chris@87: typedef PyObject * (*binaryfunc)(PyObject *, PyObject *); Chris@87: typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *); Chris@87: typedef int (*inquiry)(PyObject *); Chris@87: typedef Py_ssize_t (*lenfunc)(PyObject *); Chris@87: typedef int (*coercion)(PyObject **, PyObject **); Chris@87: typedef PyObject *(*intargfunc)(PyObject *, int) Py_DEPRECATED(2.5); Chris@87: typedef PyObject *(*intintargfunc)(PyObject *, int, int) Py_DEPRECATED(2.5); Chris@87: typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t); Chris@87: typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t); Chris@87: typedef int(*intobjargproc)(PyObject *, int, PyObject *); Chris@87: typedef int(*intintobjargproc)(PyObject *, int, int, PyObject *); Chris@87: typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *); Chris@87: typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *); Chris@87: typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *); Chris@87: Chris@87: Chris@87: Chris@87: /* int-based buffer interface */ Chris@87: typedef int (*getreadbufferproc)(PyObject *, int, void **); Chris@87: typedef int (*getwritebufferproc)(PyObject *, int, void **); Chris@87: typedef int (*getsegcountproc)(PyObject *, int *); Chris@87: typedef int (*getcharbufferproc)(PyObject *, int, char **); Chris@87: /* ssize_t-based buffer interface */ Chris@87: typedef Py_ssize_t (*readbufferproc)(PyObject *, Py_ssize_t, void **); Chris@87: typedef Py_ssize_t (*writebufferproc)(PyObject *, Py_ssize_t, void **); Chris@87: typedef Py_ssize_t (*segcountproc)(PyObject *, Py_ssize_t *); Chris@87: typedef Py_ssize_t (*charbufferproc)(PyObject *, Py_ssize_t, char **); Chris@87: Chris@87: Chris@87: /* Py3k buffer interface */ Chris@87: typedef struct bufferinfo { Chris@87: void *buf; Chris@87: PyObject *obj; /* owned reference */ Chris@87: Py_ssize_t len; Chris@87: Py_ssize_t itemsize; /* This is Py_ssize_t so it can be Chris@87: pointed to by strides in simple case.*/ Chris@87: int readonly; Chris@87: int ndim; Chris@87: char *format; Chris@87: Py_ssize_t *shape; Chris@87: Py_ssize_t *strides; Chris@87: Py_ssize_t *suboffsets; Chris@87: Py_ssize_t smalltable[2]; /* static store for shape and strides of Chris@87: mono-dimensional buffers. */ Chris@87: void *internal; Chris@87: } Py_buffer; Chris@87: Chris@87: typedef int (*getbufferproc)(PyObject *, Py_buffer *, int); Chris@87: typedef void (*releasebufferproc)(PyObject *, Py_buffer *); Chris@87: Chris@87: /* Flags for getting buffers */ Chris@87: #define PyBUF_SIMPLE 0 Chris@87: #define PyBUF_WRITABLE 0x0001 Chris@87: /* we used to include an E, backwards compatible alias */ Chris@87: #define PyBUF_WRITEABLE PyBUF_WRITABLE Chris@87: #define PyBUF_FORMAT 0x0004 Chris@87: #define PyBUF_ND 0x0008 Chris@87: #define PyBUF_STRIDES (0x0010 | PyBUF_ND) Chris@87: #define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES) Chris@87: #define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES) Chris@87: #define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES) Chris@87: #define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES) Chris@87: Chris@87: #define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE) Chris@87: #define PyBUF_CONTIG_RO (PyBUF_ND) Chris@87: Chris@87: #define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE) Chris@87: #define PyBUF_STRIDED_RO (PyBUF_STRIDES) Chris@87: Chris@87: #define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT) Chris@87: #define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT) Chris@87: Chris@87: #define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT) Chris@87: #define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT) Chris@87: Chris@87: Chris@87: #define PyBUF_READ 0x100 Chris@87: #define PyBUF_WRITE 0x200 Chris@87: #define PyBUF_SHADOW 0x400 Chris@87: /* end Py3k buffer interface */ Chris@87: Chris@87: typedef int (*objobjproc)(PyObject *, PyObject *); Chris@87: typedef int (*visitproc)(PyObject *, void *); Chris@87: typedef int (*traverseproc)(PyObject *, visitproc, void *); Chris@87: Chris@87: typedef struct { Chris@87: /* For numbers without flag bit Py_TPFLAGS_CHECKTYPES set, all Chris@87: arguments are guaranteed to be of the object's type (modulo Chris@87: coercion hacks -- i.e. if the type's coercion function Chris@87: returns other types, then these are allowed as well). Numbers that Chris@87: have the Py_TPFLAGS_CHECKTYPES flag bit set should check *both* Chris@87: arguments for proper type and implement the necessary conversions Chris@87: in the slot functions themselves. */ Chris@87: Chris@87: binaryfunc nb_add; Chris@87: binaryfunc nb_subtract; Chris@87: binaryfunc nb_multiply; Chris@87: binaryfunc nb_divide; Chris@87: binaryfunc nb_remainder; Chris@87: binaryfunc nb_divmod; Chris@87: ternaryfunc nb_power; Chris@87: unaryfunc nb_negative; Chris@87: unaryfunc nb_positive; Chris@87: unaryfunc nb_absolute; Chris@87: inquiry nb_nonzero; Chris@87: unaryfunc nb_invert; Chris@87: binaryfunc nb_lshift; Chris@87: binaryfunc nb_rshift; Chris@87: binaryfunc nb_and; Chris@87: binaryfunc nb_xor; Chris@87: binaryfunc nb_or; Chris@87: coercion nb_coerce; Chris@87: unaryfunc nb_int; Chris@87: unaryfunc nb_long; Chris@87: unaryfunc nb_float; Chris@87: unaryfunc nb_oct; Chris@87: unaryfunc nb_hex; Chris@87: /* Added in release 2.0 */ Chris@87: binaryfunc nb_inplace_add; Chris@87: binaryfunc nb_inplace_subtract; Chris@87: binaryfunc nb_inplace_multiply; Chris@87: binaryfunc nb_inplace_divide; Chris@87: binaryfunc nb_inplace_remainder; Chris@87: ternaryfunc nb_inplace_power; Chris@87: binaryfunc nb_inplace_lshift; Chris@87: binaryfunc nb_inplace_rshift; Chris@87: binaryfunc nb_inplace_and; Chris@87: binaryfunc nb_inplace_xor; Chris@87: binaryfunc nb_inplace_or; Chris@87: Chris@87: /* Added in release 2.2 */ Chris@87: /* The following require the Py_TPFLAGS_HAVE_CLASS flag */ Chris@87: binaryfunc nb_floor_divide; Chris@87: binaryfunc nb_true_divide; Chris@87: binaryfunc nb_inplace_floor_divide; Chris@87: binaryfunc nb_inplace_true_divide; Chris@87: Chris@87: /* Added in release 2.5 */ Chris@87: unaryfunc nb_index; Chris@87: } PyNumberMethods; Chris@87: Chris@87: typedef struct { Chris@87: lenfunc sq_length; Chris@87: binaryfunc sq_concat; Chris@87: ssizeargfunc sq_repeat; Chris@87: ssizeargfunc sq_item; Chris@87: ssizessizeargfunc sq_slice; Chris@87: ssizeobjargproc sq_ass_item; Chris@87: ssizessizeobjargproc sq_ass_slice; Chris@87: objobjproc sq_contains; Chris@87: /* Added in release 2.0 */ Chris@87: binaryfunc sq_inplace_concat; Chris@87: ssizeargfunc sq_inplace_repeat; Chris@87: } PySequenceMethods; Chris@87: Chris@87: typedef struct { Chris@87: lenfunc mp_length; Chris@87: binaryfunc mp_subscript; Chris@87: objobjargproc mp_ass_subscript; Chris@87: } PyMappingMethods; Chris@87: Chris@87: typedef struct { Chris@87: readbufferproc bf_getreadbuffer; Chris@87: writebufferproc bf_getwritebuffer; Chris@87: segcountproc bf_getsegcount; Chris@87: charbufferproc bf_getcharbuffer; Chris@87: getbufferproc bf_getbuffer; Chris@87: releasebufferproc bf_releasebuffer; Chris@87: } PyBufferProcs; Chris@87: Chris@87: Chris@87: typedef void (*freefunc)(void *); Chris@87: typedef void (*destructor)(PyObject *); Chris@87: typedef int (*printfunc)(PyObject *, FILE *, int); Chris@87: typedef PyObject *(*getattrfunc)(PyObject *, char *); Chris@87: typedef PyObject *(*getattrofunc)(PyObject *, PyObject *); Chris@87: typedef int (*setattrfunc)(PyObject *, char *, PyObject *); Chris@87: typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *); Chris@87: typedef int (*cmpfunc)(PyObject *, PyObject *); Chris@87: typedef PyObject *(*reprfunc)(PyObject *); Chris@87: typedef long (*hashfunc)(PyObject *); Chris@87: typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int); Chris@87: typedef PyObject *(*getiterfunc) (PyObject *); Chris@87: typedef PyObject *(*iternextfunc) (PyObject *); Chris@87: typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *); Chris@87: typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *); Chris@87: typedef int (*initproc)(PyObject *, PyObject *, PyObject *); Chris@87: typedef PyObject *(*newfunc)(struct _typeobject *, PyObject *, PyObject *); Chris@87: typedef PyObject *(*allocfunc)(struct _typeobject *, Py_ssize_t); Chris@87: Chris@87: typedef struct _typeobject { Chris@87: PyObject_VAR_HEAD Chris@87: const char *tp_name; /* For printing, in format "." */ Chris@87: Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */ Chris@87: Chris@87: /* Methods to implement standard operations */ Chris@87: Chris@87: destructor tp_dealloc; Chris@87: printfunc tp_print; Chris@87: getattrfunc tp_getattr; Chris@87: setattrfunc tp_setattr; Chris@87: cmpfunc tp_compare; Chris@87: reprfunc tp_repr; Chris@87: Chris@87: /* Method suites for standard classes */ Chris@87: Chris@87: PyNumberMethods *tp_as_number; Chris@87: PySequenceMethods *tp_as_sequence; Chris@87: PyMappingMethods *tp_as_mapping; Chris@87: Chris@87: /* More standard operations (here for binary compatibility) */ Chris@87: Chris@87: hashfunc tp_hash; Chris@87: ternaryfunc tp_call; Chris@87: reprfunc tp_str; Chris@87: getattrofunc tp_getattro; Chris@87: setattrofunc tp_setattro; Chris@87: Chris@87: /* Functions to access object as input/output buffer */ Chris@87: PyBufferProcs *tp_as_buffer; Chris@87: Chris@87: /* Flags to define presence of optional/expanded features */ Chris@87: long tp_flags; Chris@87: Chris@87: const char *tp_doc; /* Documentation string */ Chris@87: Chris@87: /* Assigned meaning in release 2.0 */ Chris@87: /* call function for all accessible objects */ Chris@87: traverseproc tp_traverse; Chris@87: Chris@87: /* delete references to contained objects */ Chris@87: inquiry tp_clear; Chris@87: Chris@87: /* Assigned meaning in release 2.1 */ Chris@87: /* rich comparisons */ Chris@87: richcmpfunc tp_richcompare; Chris@87: Chris@87: /* weak reference enabler */ Chris@87: Py_ssize_t tp_weaklistoffset; Chris@87: Chris@87: /* Added in release 2.2 */ Chris@87: /* Iterators */ Chris@87: getiterfunc tp_iter; Chris@87: iternextfunc tp_iternext; Chris@87: Chris@87: /* Attribute descriptor and subclassing stuff */ Chris@87: struct PyMethodDef *tp_methods; Chris@87: struct PyMemberDef *tp_members; Chris@87: struct PyGetSetDef *tp_getset; Chris@87: struct _typeobject *tp_base; Chris@87: PyObject *tp_dict; Chris@87: descrgetfunc tp_descr_get; Chris@87: descrsetfunc tp_descr_set; Chris@87: Py_ssize_t tp_dictoffset; Chris@87: initproc tp_init; Chris@87: allocfunc tp_alloc; Chris@87: newfunc tp_new; Chris@87: freefunc tp_free; /* Low-level free-memory routine */ Chris@87: inquiry tp_is_gc; /* For PyObject_IS_GC */ Chris@87: PyObject *tp_bases; Chris@87: PyObject *tp_mro; /* method resolution order */ Chris@87: PyObject *tp_cache; Chris@87: PyObject *tp_subclasses; Chris@87: PyObject *tp_weaklist; Chris@87: destructor tp_del; Chris@87: Chris@87: /* Type attribute cache version tag. Added in version 2.6 */ Chris@87: unsigned int tp_version_tag; Chris@87: Chris@87: #ifdef COUNT_ALLOCS Chris@87: /* these must be last and never explicitly initialized */ Chris@87: Py_ssize_t tp_allocs; Chris@87: Py_ssize_t tp_frees; Chris@87: Py_ssize_t tp_maxalloc; Chris@87: struct _typeobject *tp_prev; Chris@87: struct _typeobject *tp_next; Chris@87: #endif Chris@87: } PyTypeObject; Chris@87: Chris@87: Chris@87: /* The *real* layout of a type object when allocated on the heap */ Chris@87: typedef struct _heaptypeobject { Chris@87: /* Note: there's a dependency on the order of these members Chris@87: in slotptr() in typeobject.c . */ Chris@87: PyTypeObject ht_type; Chris@87: PyNumberMethods as_number; Chris@87: PyMappingMethods as_mapping; Chris@87: PySequenceMethods as_sequence; /* as_sequence comes after as_mapping, Chris@87: so that the mapping wins when both Chris@87: the mapping and the sequence define Chris@87: a given operator (e.g. __getitem__). Chris@87: see add_operators() in typeobject.c . */ Chris@87: PyBufferProcs as_buffer; Chris@87: PyObject *ht_name, *ht_slots; Chris@87: /* here are optional user slots, followed by the members. */ Chris@87: } PyHeapTypeObject; Chris@87: Chris@87: /* access macro to the members which are floating "behind" the object */ Chris@87: #define PyHeapType_GET_MEMBERS(etype) \ Chris@87: ((PyMemberDef *)(((char *)etype) + Py_TYPE(etype)->tp_basicsize)) Chris@87: Chris@87: Chris@87: /* Generic type check */ Chris@87: PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *); Chris@87: #define PyObject_TypeCheck(ob, tp) \ Chris@87: (Py_TYPE(ob) == (tp) || PyType_IsSubtype(Py_TYPE(ob), (tp))) Chris@87: Chris@87: PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */ Chris@87: PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */ Chris@87: PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */ Chris@87: Chris@87: #define PyType_Check(op) \ Chris@87: PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS) Chris@87: #define PyType_CheckExact(op) (Py_TYPE(op) == &PyType_Type) Chris@87: Chris@87: PyAPI_FUNC(int) PyType_Ready(PyTypeObject *); Chris@87: PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t); Chris@87: PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *, Chris@87: PyObject *, PyObject *); Chris@87: PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *); Chris@87: PyAPI_FUNC(PyObject *) _PyObject_LookupSpecial(PyObject *, char *, PyObject **); Chris@87: PyAPI_FUNC(unsigned int) PyType_ClearCache(void); Chris@87: PyAPI_FUNC(void) PyType_Modified(PyTypeObject *); Chris@87: Chris@87: /* Generic operations on objects */ Chris@87: PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int); Chris@87: PyAPI_FUNC(void) _PyObject_Dump(PyObject *); Chris@87: PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *); Chris@87: PyAPI_FUNC(PyObject *) _PyObject_Str(PyObject *); Chris@87: PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *); Chris@87: #define PyObject_Bytes PyObject_Str Chris@87: #ifdef Py_USING_UNICODE Chris@87: PyAPI_FUNC(PyObject *) PyObject_Unicode(PyObject *); Chris@87: #endif Chris@87: PyAPI_FUNC(int) PyObject_Compare(PyObject *, PyObject *); Chris@87: PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int); Chris@87: PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int); Chris@87: PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *); Chris@87: PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *); Chris@87: PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *); Chris@87: PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *); Chris@87: PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *); Chris@87: PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *); Chris@87: PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *); Chris@87: PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *); Chris@87: PyAPI_FUNC(PyObject *) _PyObject_NextNotImplemented(PyObject *); Chris@87: PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *); Chris@87: PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, Chris@87: PyObject *, PyObject *); Chris@87: PyAPI_FUNC(long) PyObject_Hash(PyObject *); Chris@87: PyAPI_FUNC(long) PyObject_HashNotImplemented(PyObject *); Chris@87: PyAPI_FUNC(int) PyObject_IsTrue(PyObject *); Chris@87: PyAPI_FUNC(int) PyObject_Not(PyObject *); Chris@87: PyAPI_FUNC(int) PyCallable_Check(PyObject *); Chris@87: PyAPI_FUNC(int) PyNumber_Coerce(PyObject **, PyObject **); Chris@87: PyAPI_FUNC(int) PyNumber_CoerceEx(PyObject **, PyObject **); Chris@87: Chris@87: PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *); Chris@87: Chris@87: /* A slot function whose address we need to compare */ Chris@87: extern int _PyObject_SlotCompare(PyObject *, PyObject *); Chris@87: /* Same as PyObject_Generic{Get,Set}Attr, but passing the attributes Chris@87: dict as the last parameter. */ Chris@87: PyAPI_FUNC(PyObject *) Chris@87: _PyObject_GenericGetAttrWithDict(PyObject *, PyObject *, PyObject *); Chris@87: PyAPI_FUNC(int) Chris@87: _PyObject_GenericSetAttrWithDict(PyObject *, PyObject *, Chris@87: PyObject *, PyObject *); Chris@87: Chris@87: Chris@87: /* PyObject_Dir(obj) acts like Python __builtin__.dir(obj), returning a Chris@87: list of strings. PyObject_Dir(NULL) is like __builtin__.dir(), Chris@87: returning the names of the current locals. In this case, if there are Chris@87: no current locals, NULL is returned, and PyErr_Occurred() is false. Chris@87: */ Chris@87: PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *); Chris@87: Chris@87: Chris@87: /* Helpers for printing recursive container types */ Chris@87: PyAPI_FUNC(int) Py_ReprEnter(PyObject *); Chris@87: PyAPI_FUNC(void) Py_ReprLeave(PyObject *); Chris@87: Chris@87: /* Helpers for hash functions */ Chris@87: PyAPI_FUNC(long) _Py_HashDouble(double); Chris@87: PyAPI_FUNC(long) _Py_HashPointer(void*); Chris@87: Chris@87: typedef struct { Chris@87: long prefix; Chris@87: long suffix; Chris@87: } _Py_HashSecret_t; Chris@87: PyAPI_DATA(_Py_HashSecret_t) _Py_HashSecret; Chris@87: Chris@87: #ifdef Py_DEBUG Chris@87: PyAPI_DATA(int) _Py_HashSecret_Initialized; Chris@87: #endif Chris@87: Chris@87: /* Helper for passing objects to printf and the like. Chris@87: Leaks refcounts. Don't use it! Chris@87: */ Chris@87: #define PyObject_REPR(obj) PyString_AS_STRING(PyObject_Repr(obj)) Chris@87: Chris@87: /* Flag bits for printing: */ Chris@87: #define Py_PRINT_RAW 1 /* No string quotes etc. */ Chris@87: Chris@87: /* Chris@87: `Type flags (tp_flags) Chris@87: Chris@87: These flags are used to extend the type structure in a backwards-compatible Chris@87: fashion. Extensions can use the flags to indicate (and test) when a given Chris@87: type structure contains a new feature. The Python core will use these when Chris@87: introducing new functionality between major revisions (to avoid mid-version Chris@87: changes in the PYTHON_API_VERSION). Chris@87: Chris@87: Arbitration of the flag bit positions will need to be coordinated among Chris@87: all extension writers who publically release their extensions (this will Chris@87: be fewer than you might expect!).. Chris@87: Chris@87: Python 1.5.2 introduced the bf_getcharbuffer slot into PyBufferProcs. Chris@87: Chris@87: Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value. Chris@87: Chris@87: Code can use PyType_HasFeature(type_ob, flag_value) to test whether the Chris@87: given type object has a specified feature. Chris@87: Chris@87: NOTE: when building the core, Py_TPFLAGS_DEFAULT includes Chris@87: Py_TPFLAGS_HAVE_VERSION_TAG; outside the core, it doesn't. This is so Chris@87: that extensions that modify tp_dict of their own types directly don't Chris@87: break, since this was allowed in 2.5. In 3.0 they will have to Chris@87: manually remove this flag though! Chris@87: */ Chris@87: Chris@87: /* PyBufferProcs contains bf_getcharbuffer */ Chris@87: #define Py_TPFLAGS_HAVE_GETCHARBUFFER (1L<<0) Chris@87: Chris@87: /* PySequenceMethods contains sq_contains */ Chris@87: #define Py_TPFLAGS_HAVE_SEQUENCE_IN (1L<<1) Chris@87: Chris@87: /* This is here for backwards compatibility. Extensions that use the old GC Chris@87: * API will still compile but the objects will not be tracked by the GC. */ Chris@87: #define Py_TPFLAGS_GC 0 /* used to be (1L<<2) */ Chris@87: Chris@87: /* PySequenceMethods and PyNumberMethods contain in-place operators */ Chris@87: #define Py_TPFLAGS_HAVE_INPLACEOPS (1L<<3) Chris@87: Chris@87: /* PyNumberMethods do their own coercion */ Chris@87: #define Py_TPFLAGS_CHECKTYPES (1L<<4) Chris@87: Chris@87: /* tp_richcompare is defined */ Chris@87: #define Py_TPFLAGS_HAVE_RICHCOMPARE (1L<<5) Chris@87: Chris@87: /* Objects which are weakly referencable if their tp_weaklistoffset is >0 */ Chris@87: #define Py_TPFLAGS_HAVE_WEAKREFS (1L<<6) Chris@87: Chris@87: /* tp_iter is defined */ Chris@87: #define Py_TPFLAGS_HAVE_ITER (1L<<7) Chris@87: Chris@87: /* New members introduced by Python 2.2 exist */ Chris@87: #define Py_TPFLAGS_HAVE_CLASS (1L<<8) Chris@87: Chris@87: /* Set if the type object is dynamically allocated */ Chris@87: #define Py_TPFLAGS_HEAPTYPE (1L<<9) Chris@87: Chris@87: /* Set if the type allows subclassing */ Chris@87: #define Py_TPFLAGS_BASETYPE (1L<<10) Chris@87: Chris@87: /* Set if the type is 'ready' -- fully initialized */ Chris@87: #define Py_TPFLAGS_READY (1L<<12) Chris@87: Chris@87: /* Set while the type is being 'readied', to prevent recursive ready calls */ Chris@87: #define Py_TPFLAGS_READYING (1L<<13) Chris@87: Chris@87: /* Objects support garbage collection (see objimp.h) */ Chris@87: #define Py_TPFLAGS_HAVE_GC (1L<<14) Chris@87: Chris@87: /* These two bits are preserved for Stackless Python, next after this is 17 */ Chris@87: #ifdef STACKLESS Chris@87: #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3L<<15) Chris@87: #else Chris@87: #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0 Chris@87: #endif Chris@87: Chris@87: /* Objects support nb_index in PyNumberMethods */ Chris@87: #define Py_TPFLAGS_HAVE_INDEX (1L<<17) Chris@87: Chris@87: /* Objects support type attribute cache */ Chris@87: #define Py_TPFLAGS_HAVE_VERSION_TAG (1L<<18) Chris@87: #define Py_TPFLAGS_VALID_VERSION_TAG (1L<<19) Chris@87: Chris@87: /* Type is abstract and cannot be instantiated */ Chris@87: #define Py_TPFLAGS_IS_ABSTRACT (1L<<20) Chris@87: Chris@87: /* Has the new buffer protocol */ Chris@87: #define Py_TPFLAGS_HAVE_NEWBUFFER (1L<<21) Chris@87: Chris@87: /* These flags are used to determine if a type is a subclass. */ Chris@87: #define Py_TPFLAGS_INT_SUBCLASS (1L<<23) Chris@87: #define Py_TPFLAGS_LONG_SUBCLASS (1L<<24) Chris@87: #define Py_TPFLAGS_LIST_SUBCLASS (1L<<25) Chris@87: #define Py_TPFLAGS_TUPLE_SUBCLASS (1L<<26) Chris@87: #define Py_TPFLAGS_STRING_SUBCLASS (1L<<27) Chris@87: #define Py_TPFLAGS_UNICODE_SUBCLASS (1L<<28) Chris@87: #define Py_TPFLAGS_DICT_SUBCLASS (1L<<29) Chris@87: #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1L<<30) Chris@87: #define Py_TPFLAGS_TYPE_SUBCLASS (1L<<31) Chris@87: Chris@87: #define Py_TPFLAGS_DEFAULT_EXTERNAL ( \ Chris@87: Py_TPFLAGS_HAVE_GETCHARBUFFER | \ Chris@87: Py_TPFLAGS_HAVE_SEQUENCE_IN | \ Chris@87: Py_TPFLAGS_HAVE_INPLACEOPS | \ Chris@87: Py_TPFLAGS_HAVE_RICHCOMPARE | \ Chris@87: Py_TPFLAGS_HAVE_WEAKREFS | \ Chris@87: Py_TPFLAGS_HAVE_ITER | \ Chris@87: Py_TPFLAGS_HAVE_CLASS | \ Chris@87: Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \ Chris@87: Py_TPFLAGS_HAVE_INDEX | \ Chris@87: 0) Chris@87: #define Py_TPFLAGS_DEFAULT_CORE (Py_TPFLAGS_DEFAULT_EXTERNAL | \ Chris@87: Py_TPFLAGS_HAVE_VERSION_TAG) Chris@87: Chris@87: #ifdef Py_BUILD_CORE Chris@87: #define Py_TPFLAGS_DEFAULT Py_TPFLAGS_DEFAULT_CORE Chris@87: #else Chris@87: #define Py_TPFLAGS_DEFAULT Py_TPFLAGS_DEFAULT_EXTERNAL Chris@87: #endif Chris@87: Chris@87: #define PyType_HasFeature(t,f) (((t)->tp_flags & (f)) != 0) Chris@87: #define PyType_FastSubclass(t,f) PyType_HasFeature(t,f) Chris@87: Chris@87: Chris@87: /* Chris@87: The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement Chris@87: reference counts. Py_DECREF calls the object's deallocator function when Chris@87: the refcount falls to 0; for Chris@87: objects that don't contain references to other objects or heap memory Chris@87: this can be the standard function free(). Both macros can be used Chris@87: wherever a void expression is allowed. The argument must not be a Chris@87: NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead. Chris@87: The macro _Py_NewReference(op) initialize reference counts to 1, and Chris@87: in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional Chris@87: bookkeeping appropriate to the special build. Chris@87: Chris@87: We assume that the reference count field can never overflow; this can Chris@87: be proven when the size of the field is the same as the pointer size, so Chris@87: we ignore the possibility. Provided a C int is at least 32 bits (which Chris@87: is implicitly assumed in many parts of this code), that's enough for Chris@87: about 2**31 references to an object. Chris@87: Chris@87: XXX The following became out of date in Python 2.2, but I'm not sure Chris@87: XXX what the full truth is now. Certainly, heap-allocated type objects Chris@87: XXX can and should be deallocated. Chris@87: Type objects should never be deallocated; the type pointer in an object Chris@87: is not considered to be a reference to the type object, to save Chris@87: complications in the deallocation function. (This is actually a Chris@87: decision that's up to the implementer of each new type so if you want, Chris@87: you can count such references to the type object.) Chris@87: Chris@87: *** WARNING*** The Py_DECREF macro must have a side-effect-free argument Chris@87: since it may evaluate its argument multiple times. (The alternative Chris@87: would be to mace it a proper function or assign it to a global temporary Chris@87: variable first, both of which are slower; and in a multi-threaded Chris@87: environment the global variable trick is not safe.) Chris@87: */ Chris@87: Chris@87: /* First define a pile of simple helper macros, one set per special Chris@87: * build symbol. These either expand to the obvious things, or to Chris@87: * nothing at all when the special mode isn't in effect. The main Chris@87: * macros can later be defined just once then, yet expand to different Chris@87: * things depending on which special build options are and aren't in effect. Chris@87: * Trust me : while painful, this is 20x easier to understand than, Chris@87: * e.g, defining _Py_NewReference five different times in a maze of nested Chris@87: * #ifdefs (we used to do that -- it was impenetrable). Chris@87: */ Chris@87: #ifdef Py_REF_DEBUG Chris@87: PyAPI_DATA(Py_ssize_t) _Py_RefTotal; Chris@87: PyAPI_FUNC(void) _Py_NegativeRefcount(const char *fname, Chris@87: int lineno, PyObject *op); Chris@87: PyAPI_FUNC(PyObject *) _PyDict_Dummy(void); Chris@87: PyAPI_FUNC(PyObject *) _PySet_Dummy(void); Chris@87: PyAPI_FUNC(Py_ssize_t) _Py_GetRefTotal(void); Chris@87: #define _Py_INC_REFTOTAL _Py_RefTotal++ Chris@87: #define _Py_DEC_REFTOTAL _Py_RefTotal-- Chris@87: #define _Py_REF_DEBUG_COMMA , Chris@87: #define _Py_CHECK_REFCNT(OP) \ Chris@87: { if (((PyObject*)OP)->ob_refcnt < 0) \ Chris@87: _Py_NegativeRefcount(__FILE__, __LINE__, \ Chris@87: (PyObject *)(OP)); \ Chris@87: } Chris@87: #else Chris@87: #define _Py_INC_REFTOTAL Chris@87: #define _Py_DEC_REFTOTAL Chris@87: #define _Py_REF_DEBUG_COMMA Chris@87: #define _Py_CHECK_REFCNT(OP) /* a semicolon */; Chris@87: #endif /* Py_REF_DEBUG */ Chris@87: Chris@87: #ifdef COUNT_ALLOCS Chris@87: PyAPI_FUNC(void) inc_count(PyTypeObject *); Chris@87: PyAPI_FUNC(void) dec_count(PyTypeObject *); Chris@87: #define _Py_INC_TPALLOCS(OP) inc_count(Py_TYPE(OP)) Chris@87: #define _Py_INC_TPFREES(OP) dec_count(Py_TYPE(OP)) Chris@87: #define _Py_DEC_TPFREES(OP) Py_TYPE(OP)->tp_frees-- Chris@87: #define _Py_COUNT_ALLOCS_COMMA , Chris@87: #else Chris@87: #define _Py_INC_TPALLOCS(OP) Chris@87: #define _Py_INC_TPFREES(OP) Chris@87: #define _Py_DEC_TPFREES(OP) Chris@87: #define _Py_COUNT_ALLOCS_COMMA Chris@87: #endif /* COUNT_ALLOCS */ Chris@87: Chris@87: #ifdef Py_TRACE_REFS Chris@87: /* Py_TRACE_REFS is such major surgery that we call external routines. */ Chris@87: PyAPI_FUNC(void) _Py_NewReference(PyObject *); Chris@87: PyAPI_FUNC(void) _Py_ForgetReference(PyObject *); Chris@87: PyAPI_FUNC(void) _Py_Dealloc(PyObject *); Chris@87: PyAPI_FUNC(void) _Py_PrintReferences(FILE *); Chris@87: PyAPI_FUNC(void) _Py_PrintReferenceAddresses(FILE *); Chris@87: PyAPI_FUNC(void) _Py_AddToAllObjects(PyObject *, int force); Chris@87: Chris@87: #else Chris@87: /* Without Py_TRACE_REFS, there's little enough to do that we expand code Chris@87: * inline. Chris@87: */ Chris@87: #define _Py_NewReference(op) ( \ Chris@87: _Py_INC_TPALLOCS(op) _Py_COUNT_ALLOCS_COMMA \ Chris@87: _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \ Chris@87: Py_REFCNT(op) = 1) Chris@87: Chris@87: #define _Py_ForgetReference(op) _Py_INC_TPFREES(op) Chris@87: Chris@87: #define _Py_Dealloc(op) ( \ Chris@87: _Py_INC_TPFREES(op) _Py_COUNT_ALLOCS_COMMA \ Chris@87: (*Py_TYPE(op)->tp_dealloc)((PyObject *)(op))) Chris@87: #endif /* !Py_TRACE_REFS */ Chris@87: Chris@87: #define Py_INCREF(op) ( \ Chris@87: _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \ Chris@87: ((PyObject*)(op))->ob_refcnt++) Chris@87: Chris@87: #define Py_DECREF(op) \ Chris@87: do { \ Chris@87: if (_Py_DEC_REFTOTAL _Py_REF_DEBUG_COMMA \ Chris@87: --((PyObject*)(op))->ob_refcnt != 0) \ Chris@87: _Py_CHECK_REFCNT(op) \ Chris@87: else \ Chris@87: _Py_Dealloc((PyObject *)(op)); \ Chris@87: } while (0) Chris@87: Chris@87: /* Safely decref `op` and set `op` to NULL, especially useful in tp_clear Chris@87: * and tp_dealloc implementatons. Chris@87: * Chris@87: * Note that "the obvious" code can be deadly: Chris@87: * Chris@87: * Py_XDECREF(op); Chris@87: * op = NULL; Chris@87: * Chris@87: * Typically, `op` is something like self->containee, and `self` is done Chris@87: * using its `containee` member. In the code sequence above, suppose Chris@87: * `containee` is non-NULL with a refcount of 1. Its refcount falls to Chris@87: * 0 on the first line, which can trigger an arbitrary amount of code, Chris@87: * possibly including finalizers (like __del__ methods or weakref callbacks) Chris@87: * coded in Python, which in turn can release the GIL and allow other threads Chris@87: * to run, etc. Such code may even invoke methods of `self` again, or cause Chris@87: * cyclic gc to trigger, but-- oops! --self->containee still points to the Chris@87: * object being torn down, and it may be in an insane state while being torn Chris@87: * down. This has in fact been a rich historic source of miserable (rare & Chris@87: * hard-to-diagnose) segfaulting (and other) bugs. Chris@87: * Chris@87: * The safe way is: Chris@87: * Chris@87: * Py_CLEAR(op); Chris@87: * Chris@87: * That arranges to set `op` to NULL _before_ decref'ing, so that any code Chris@87: * triggered as a side-effect of `op` getting torn down no longer believes Chris@87: * `op` points to a valid object. Chris@87: * Chris@87: * There are cases where it's safe to use the naive code, but they're brittle. Chris@87: * For example, if `op` points to a Python integer, you know that destroying Chris@87: * one of those can't cause problems -- but in part that relies on that Chris@87: * Python integers aren't currently weakly referencable. Best practice is Chris@87: * to use Py_CLEAR() even if you can't think of a reason for why you need to. Chris@87: */ Chris@87: #define Py_CLEAR(op) \ Chris@87: do { \ Chris@87: if (op) { \ Chris@87: PyObject *_py_tmp = (PyObject *)(op); \ Chris@87: (op) = NULL; \ Chris@87: Py_DECREF(_py_tmp); \ Chris@87: } \ Chris@87: } while (0) Chris@87: Chris@87: /* Macros to use in case the object pointer may be NULL: */ Chris@87: #define Py_XINCREF(op) do { if ((op) == NULL) ; else Py_INCREF(op); } while (0) Chris@87: #define Py_XDECREF(op) do { if ((op) == NULL) ; else Py_DECREF(op); } while (0) Chris@87: Chris@87: /* Chris@87: These are provided as conveniences to Python runtime embedders, so that Chris@87: they can have object code that is not dependent on Python compilation flags. Chris@87: */ Chris@87: PyAPI_FUNC(void) Py_IncRef(PyObject *); Chris@87: PyAPI_FUNC(void) Py_DecRef(PyObject *); Chris@87: Chris@87: /* Chris@87: _Py_NoneStruct is an object of undefined type which can be used in contexts Chris@87: where NULL (nil) is not suitable (since NULL often means 'error'). Chris@87: Chris@87: Don't forget to apply Py_INCREF() when returning this value!!! Chris@87: */ Chris@87: PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */ Chris@87: #define Py_None (&_Py_NoneStruct) Chris@87: Chris@87: /* Macro for returning Py_None from a function */ Chris@87: #define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None Chris@87: Chris@87: /* Chris@87: Py_NotImplemented is a singleton used to signal that an operation is Chris@87: not implemented for a given type combination. Chris@87: */ Chris@87: PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */ Chris@87: #define Py_NotImplemented (&_Py_NotImplementedStruct) Chris@87: Chris@87: /* Rich comparison opcodes */ Chris@87: #define Py_LT 0 Chris@87: #define Py_LE 1 Chris@87: #define Py_EQ 2 Chris@87: #define Py_NE 3 Chris@87: #define Py_GT 4 Chris@87: #define Py_GE 5 Chris@87: Chris@87: /* Maps Py_LT to Py_GT, ..., Py_GE to Py_LE. Chris@87: * Defined in object.c. Chris@87: */ Chris@87: PyAPI_DATA(int) _Py_SwappedOp[]; Chris@87: Chris@87: /* Chris@87: Define staticforward and statichere for source compatibility with old Chris@87: C extensions. Chris@87: Chris@87: The staticforward define was needed to support certain broken C Chris@87: compilers (notably SCO ODT 3.0, perhaps early AIX as well) botched the Chris@87: static keyword when it was used with a forward declaration of a static Chris@87: initialized structure. Standard C allows the forward declaration with Chris@87: static, and we've decided to stop catering to broken C compilers. Chris@87: (In fact, we expect that the compilers are all fixed eight years later.) Chris@87: */ Chris@87: Chris@87: #define staticforward static Chris@87: #define statichere static Chris@87: Chris@87: Chris@87: /* Chris@87: More conventions Chris@87: ================ Chris@87: Chris@87: Argument Checking Chris@87: ----------------- Chris@87: Chris@87: Functions that take objects as arguments normally don't check for nil Chris@87: arguments, but they do check the type of the argument, and return an Chris@87: error if the function doesn't apply to the type. Chris@87: Chris@87: Failure Modes Chris@87: ------------- Chris@87: Chris@87: Functions may fail for a variety of reasons, including running out of Chris@87: memory. This is communicated to the caller in two ways: an error string Chris@87: is set (see errors.h), and the function result differs: functions that Chris@87: normally return a pointer return NULL for failure, functions returning Chris@87: an integer return -1 (which could be a legal return value too!), and Chris@87: other functions return 0 for success and -1 for failure. Chris@87: Callers should always check for errors before using the result. If Chris@87: an error was set, the caller must either explicitly clear it, or pass Chris@87: the error on to its caller. Chris@87: Chris@87: Reference Counts Chris@87: ---------------- Chris@87: Chris@87: It takes a while to get used to the proper usage of reference counts. Chris@87: Chris@87: Functions that create an object set the reference count to 1; such new Chris@87: objects must be stored somewhere or destroyed again with Py_DECREF(). Chris@87: Some functions that 'store' objects, such as PyTuple_SetItem() and Chris@87: PyList_SetItem(), Chris@87: don't increment the reference count of the object, since the most Chris@87: frequent use is to store a fresh object. Functions that 'retrieve' Chris@87: objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also Chris@87: don't increment Chris@87: the reference count, since most frequently the object is only looked at Chris@87: quickly. Thus, to retrieve an object and store it again, the caller Chris@87: must call Py_INCREF() explicitly. Chris@87: Chris@87: NOTE: functions that 'consume' a reference count, like Chris@87: PyList_SetItem(), consume the reference even if the object wasn't Chris@87: successfully stored, to simplify error handling. Chris@87: Chris@87: It seems attractive to make other functions that take an object as Chris@87: argument consume a reference count; however, this may quickly get Chris@87: confusing (even the current practice is already confusing). Consider Chris@87: it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at Chris@87: times. Chris@87: */ Chris@87: Chris@87: Chris@87: /* Trashcan mechanism, thanks to Christian Tismer. Chris@87: Chris@87: When deallocating a container object, it's possible to trigger an unbounded Chris@87: chain of deallocations, as each Py_DECREF in turn drops the refcount on "the Chris@87: next" object in the chain to 0. This can easily lead to stack faults, and Chris@87: especially in threads (which typically have less stack space to work with). Chris@87: Chris@87: A container object that participates in cyclic gc can avoid this by Chris@87: bracketing the body of its tp_dealloc function with a pair of macros: Chris@87: Chris@87: static void Chris@87: mytype_dealloc(mytype *p) Chris@87: { Chris@87: ... declarations go here ... Chris@87: Chris@87: PyObject_GC_UnTrack(p); // must untrack first Chris@87: Py_TRASHCAN_SAFE_BEGIN(p) Chris@87: ... The body of the deallocator goes here, including all calls ... Chris@87: ... to Py_DECREF on contained objects. ... Chris@87: Py_TRASHCAN_SAFE_END(p) Chris@87: } Chris@87: Chris@87: CAUTION: Never return from the middle of the body! If the body needs to Chris@87: "get out early", put a label immediately before the Py_TRASHCAN_SAFE_END Chris@87: call, and goto it. Else the call-depth counter (see below) will stay Chris@87: above 0 forever, and the trashcan will never get emptied. Chris@87: Chris@87: How it works: The BEGIN macro increments a call-depth counter. So long Chris@87: as this counter is small, the body of the deallocator is run directly without Chris@87: further ado. But if the counter gets large, it instead adds p to a list of Chris@87: objects to be deallocated later, skips the body of the deallocator, and Chris@87: resumes execution after the END macro. The tp_dealloc routine then returns Chris@87: without deallocating anything (and so unbounded call-stack depth is avoided). Chris@87: Chris@87: When the call stack finishes unwinding again, code generated by the END macro Chris@87: notices this, and calls another routine to deallocate all the objects that Chris@87: may have been added to the list of deferred deallocations. In effect, a Chris@87: chain of N deallocations is broken into N / PyTrash_UNWIND_LEVEL pieces, Chris@87: with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL. Chris@87: */ Chris@87: Chris@87: /* This is the old private API, invoked by the macros before 2.7.4. Chris@87: Kept for binary compatibility of extensions. */ Chris@87: PyAPI_FUNC(void) _PyTrash_deposit_object(PyObject*); Chris@87: PyAPI_FUNC(void) _PyTrash_destroy_chain(void); Chris@87: PyAPI_DATA(int) _PyTrash_delete_nesting; Chris@87: PyAPI_DATA(PyObject *) _PyTrash_delete_later; Chris@87: Chris@87: /* The new thread-safe private API, invoked by the macros below. */ Chris@87: PyAPI_FUNC(void) _PyTrash_thread_deposit_object(PyObject*); Chris@87: PyAPI_FUNC(void) _PyTrash_thread_destroy_chain(void); Chris@87: Chris@87: #define PyTrash_UNWIND_LEVEL 50 Chris@87: Chris@87: /* Note the workaround for when the thread state is NULL (issue #17703) */ Chris@87: #define Py_TRASHCAN_SAFE_BEGIN(op) \ Chris@87: do { \ Chris@87: PyThreadState *_tstate = PyThreadState_GET(); \ Chris@87: if (!_tstate || \ Chris@87: _tstate->trash_delete_nesting < PyTrash_UNWIND_LEVEL) { \ Chris@87: if (_tstate) \ Chris@87: ++_tstate->trash_delete_nesting; Chris@87: /* The body of the deallocator is here. */ Chris@87: #define Py_TRASHCAN_SAFE_END(op) \ Chris@87: if (_tstate) { \ Chris@87: --_tstate->trash_delete_nesting; \ Chris@87: if (_tstate->trash_delete_later \ Chris@87: && _tstate->trash_delete_nesting <= 0) \ Chris@87: _PyTrash_thread_destroy_chain(); \ Chris@87: } \ Chris@87: } \ Chris@87: else \ Chris@87: _PyTrash_thread_deposit_object((PyObject*)op); \ Chris@87: } while (0); Chris@87: Chris@87: #ifdef __cplusplus Chris@87: } Chris@87: #endif Chris@87: #endif /* !Py_OBJECT_H */