blob: 37537859668d6c67c04187667aeba556000c99d8 [file] [log] [blame]
Guido van Rossuma3309961993-07-28 09:05:47 +00001#ifndef Py_OBJECT_H
2#define Py_OBJECT_H
3#ifdef __cplusplus
4extern "C" {
5#endif
6
Guido van Rossumf70e43a1991-02-19 12:39:46 +00007
Guido van Rossum85a5fbb1990-10-14 12:07:46 +00008/* Object and type object interface */
9
10/*
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000011Objects are structures allocated on the heap. Special rules apply to
12the use of objects to ensure they are properly garbage-collected.
13Objects are never allocated statically or on the stack; they must be
14accessed through special macros and functions only. (Type objects are
15exceptions to the first rule; the standard types are represented by
Tim Peters4be93d02002-07-07 19:59:50 +000016statically initialized type objects, although work on type/class unification
17for Python 2.2 made it possible to have heap-allocated type objects too).
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000018
19An object has a 'reference count' that is increased or decreased when a
20pointer to the object is copied or deleted; when the reference count
21reaches zero there are no references to the object left and it can be
22removed from the heap.
23
24An object has a 'type' that determines what it represents and what kind
25of data it contains. An object's type is fixed when it is created.
26Types themselves are represented as objects; an object contains a
27pointer to the corresponding type object. The type itself has a type
28pointer pointing to the object representing the type 'type', which
29contains a pointer to itself!).
30
31Objects do not float around in memory; once allocated an object keeps
32the same size and address. Objects that must hold variable-size data
33can contain pointers to variable-size parts of the object. Not all
34objects of the same type have the same size; but the size cannot change
35after allocation. (These restrictions are made so a reference to an
36object can be simply a pointer -- moving an object would require
37updating all the pointers, and changing an object's size would require
38moving it if there was another object right next to it.)
39
Guido van Rossumcaa63801995-01-12 11:45:45 +000040Objects are always accessed through pointers of the type 'PyObject *'.
41The type 'PyObject' is a structure that only contains the reference count
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000042and the type pointer. The actual memory allocated for an object
43contains other data that can only be accessed after casting the pointer
44to a pointer to a longer structure type. This longer type must start
Guido van Rossumcaa63801995-01-12 11:45:45 +000045with the reference count and type fields; the macro PyObject_HEAD should be
Thomas Wouters7e474022000-07-16 12:04:32 +000046used for this (to accommodate for future changes). The implementation
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000047of a particular object type can cast the object pointer to the proper
48type and back.
49
50A standard interface exists for objects that contain an array of items
51whose size is determined when the object is allocated.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000052*/
53
Tim Peters34592512002-07-11 06:23:50 +000054/* Py_DEBUG implies Py_TRACE_REFS. */
55#if defined(Py_DEBUG) && !defined(Py_TRACE_REFS)
Tim Peters4be93d02002-07-07 19:59:50 +000056#define Py_TRACE_REFS
Tim Peters34592512002-07-11 06:23:50 +000057#endif
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000058
Tim Peters4be93d02002-07-07 19:59:50 +000059/* Py_TRACE_REFS implies Py_REF_DEBUG. */
60#if defined(Py_TRACE_REFS) && !defined(Py_REF_DEBUG)
61#define Py_REF_DEBUG
62#endif
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000063
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000064#if defined(Py_LIMITED_API) && defined(Py_REF_DEBUG)
65#error Py_LIMITED_API is incompatible with Py_DEBUG, Py_TRACE_REFS, and Py_REF_DEBUG
66#endif
67
Tim Peters4be93d02002-07-07 19:59:50 +000068#ifdef Py_TRACE_REFS
69/* Define pointers to support a doubly-linked list of all live heap objects. */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000070#define _PyObject_HEAD_EXTRA \
71 struct _object *_ob_next; \
72 struct _object *_ob_prev;
Tim Peters4be93d02002-07-07 19:59:50 +000073
74#define _PyObject_EXTRA_INIT 0, 0,
75
76#else
77#define _PyObject_HEAD_EXTRA
78#define _PyObject_EXTRA_INIT
79#endif
80
81/* PyObject_HEAD defines the initial segment of every PyObject. */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000082#define PyObject_HEAD PyObject ob_base;
Tim Peters4be93d02002-07-07 19:59:50 +000083
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000084#define PyObject_HEAD_INIT(type) \
85 { _PyObject_EXTRA_INIT \
86 1, type },
Martin v. Löwis9f2e3462007-07-21 17:22:18 +000087
Antoine Pitrouf95a1b32010-05-09 15:52:27 +000088#define PyVarObject_HEAD_INIT(type, size) \
89 { PyObject_HEAD_INIT(type) size },
Tim Peters4be93d02002-07-07 19:59:50 +000090
91/* PyObject_VAR_HEAD defines the initial segment of all variable-size
92 * container objects. These end with a declaration of an array with 1
93 * element, but enough space is malloc'ed so that the array actually
94 * has room for ob_size elements. Note that ob_size is an element count,
95 * not necessarily a byte count.
96 */
Martin v. Löwis9f2e3462007-07-21 17:22:18 +000097#define PyObject_VAR_HEAD PyVarObject ob_base;
Martin v. Löwis18e16552006-02-15 17:27:45 +000098#define Py_INVALID_SIZE (Py_ssize_t)-1
Tim Peters803526b2002-07-07 05:13:56 +000099
Tim Peters4be93d02002-07-07 19:59:50 +0000100/* Nothing is actually declared to be a PyObject, but every pointer to
101 * a Python object can be cast to a PyObject*. This is inheritance built
102 * by hand. Similarly every pointer to a variable-size Python object can,
103 * in addition, be cast to PyVarObject*.
104 */
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000105typedef struct _object {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000106 _PyObject_HEAD_EXTRA
107 Py_ssize_t ob_refcnt;
108 struct _typeobject *ob_type;
Guido van Rossumcaa63801995-01-12 11:45:45 +0000109} PyObject;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000110
111typedef struct {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000112 PyObject ob_base;
113 Py_ssize_t ob_size; /* Number of items in variable part */
Guido van Rossumd0c87ee1997-05-15 21:31:03 +0000114} PyVarObject;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000115
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000116#define Py_REFCNT(ob) (((PyObject*)(ob))->ob_refcnt)
117#define Py_TYPE(ob) (((PyObject*)(ob))->ob_type)
118#define Py_SIZE(ob) (((PyVarObject*)(ob))->ob_size)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000119
120/*
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000121Type objects contain a string containing the type name (to help somewhat
Tim Peters4be93d02002-07-07 19:59:50 +0000122in debugging), the allocation parameters (see PyObject_New() and
123PyObject_NewVar()),
124and methods for accessing objects of the type. Methods are optional, a
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000125nil pointer meaning that particular kind of access is not available for
Guido van Rossumcaa63801995-01-12 11:45:45 +0000126this type. The Py_DECREF() macro uses the tp_dealloc method without
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000127checking for a nil pointer; it should always be implemented except if
128the implementation can guarantee that the reference count will never
Tim Peters4be93d02002-07-07 19:59:50 +0000129reach zero (e.g., for statically allocated type objects).
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000130
131NB: the methods for certain type groups are now contained in separate
132method blocks.
133*/
134
Tim Peters9ace6bc2000-07-08 00:32:04 +0000135typedef PyObject * (*unaryfunc)(PyObject *);
136typedef PyObject * (*binaryfunc)(PyObject *, PyObject *);
137typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *);
138typedef int (*inquiry)(PyObject *);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000139typedef Py_ssize_t (*lenfunc)(PyObject *);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000140typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t);
141typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000142typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *);
143typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000144typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000145
Martin v. Löwisc83bc3c2011-01-06 19:15:47 +0000146#ifndef Py_LIMITED_API
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000147/* buffer interface */
148typedef struct bufferinfo {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000149 void *buf;
150 PyObject *obj; /* owned reference */
151 Py_ssize_t len;
152 Py_ssize_t itemsize; /* This is Py_ssize_t so it can be
153 pointed to by strides in simple case.*/
154 int readonly;
155 int ndim;
156 char *format;
157 Py_ssize_t *shape;
158 Py_ssize_t *strides;
159 Py_ssize_t *suboffsets;
160 Py_ssize_t smalltable[2]; /* static store for shape and strides of
161 mono-dimensional buffers. */
162 void *internal;
Travis E. Oliphant8ae62b62007-09-23 02:00:13 +0000163} Py_buffer;
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000164
Travis E. Oliphant8ae62b62007-09-23 02:00:13 +0000165typedef int (*getbufferproc)(PyObject *, Py_buffer *, int);
166typedef void (*releasebufferproc)(PyObject *, Py_buffer *);
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000167
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000168 /* Flags for getting buffers */
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000169#define PyBUF_SIMPLE 0
Travis E. Oliphantddacf962007-10-13 21:03:27 +0000170#define PyBUF_WRITABLE 0x0001
Sean Reifscheider54cf12b2007-09-17 17:55:36 +0000171/* we used to include an E, backwards compatible alias */
172#define PyBUF_WRITEABLE PyBUF_WRITABLE
Travis E. Oliphantddacf962007-10-13 21:03:27 +0000173#define PyBUF_FORMAT 0x0004
174#define PyBUF_ND 0x0008
175#define PyBUF_STRIDES (0x0010 | PyBUF_ND)
176#define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES)
177#define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES)
178#define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES)
179#define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000180
Sean Reifscheider54cf12b2007-09-17 17:55:36 +0000181#define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000182#define PyBUF_CONTIG_RO (PyBUF_ND)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000183
Sean Reifscheider54cf12b2007-09-17 17:55:36 +0000184#define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000185#define PyBUF_STRIDED_RO (PyBUF_STRIDES)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000186
Sean Reifscheider54cf12b2007-09-17 17:55:36 +0000187#define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000188#define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000189
Sean Reifscheider54cf12b2007-09-17 17:55:36 +0000190#define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000191#define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT)
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000192
193
194#define PyBUF_READ 0x100
195#define PyBUF_WRITE 0x200
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000196
197/* End buffer interface */
Martin v. Löwisc83bc3c2011-01-06 19:15:47 +0000198#endif /* Py_LIMITED_API */
Martin v. Löwis18e16552006-02-15 17:27:45 +0000199
Tim Peters9ace6bc2000-07-08 00:32:04 +0000200typedef int (*objobjproc)(PyObject *, PyObject *);
201typedef int (*visitproc)(PyObject *, void *);
202typedef int (*traverseproc)(PyObject *, visitproc, void *);
Guido van Rossumb6775db1994-08-01 11:34:53 +0000203
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000204#ifndef Py_LIMITED_API
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000205typedef struct {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000206 /* Number implementations must check *both*
207 arguments for proper type and implement the necessary conversions
208 in the slot functions themselves. */
Neil Schemenauera7ed6942001-01-04 01:31:50 +0000209
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000210 binaryfunc nb_add;
211 binaryfunc nb_subtract;
212 binaryfunc nb_multiply;
213 binaryfunc nb_remainder;
214 binaryfunc nb_divmod;
215 ternaryfunc nb_power;
216 unaryfunc nb_negative;
217 unaryfunc nb_positive;
218 unaryfunc nb_absolute;
219 inquiry nb_bool;
220 unaryfunc nb_invert;
221 binaryfunc nb_lshift;
222 binaryfunc nb_rshift;
223 binaryfunc nb_and;
224 binaryfunc nb_xor;
225 binaryfunc nb_or;
226 unaryfunc nb_int;
227 void *nb_reserved; /* the slot formerly known as nb_long */
228 unaryfunc nb_float;
Guido van Rossum50e9fb92006-08-17 05:42:55 +0000229
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000230 binaryfunc nb_inplace_add;
231 binaryfunc nb_inplace_subtract;
232 binaryfunc nb_inplace_multiply;
233 binaryfunc nb_inplace_remainder;
234 ternaryfunc nb_inplace_power;
235 binaryfunc nb_inplace_lshift;
236 binaryfunc nb_inplace_rshift;
237 binaryfunc nb_inplace_and;
238 binaryfunc nb_inplace_xor;
239 binaryfunc nb_inplace_or;
Guido van Rossum4668b002001-08-08 05:00:18 +0000240
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000241 binaryfunc nb_floor_divide;
242 binaryfunc nb_true_divide;
243 binaryfunc nb_inplace_floor_divide;
244 binaryfunc nb_inplace_true_divide;
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000245
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000246 unaryfunc nb_index;
Guido van Rossumcaa63801995-01-12 11:45:45 +0000247} PyNumberMethods;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000248
249typedef struct {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000250 lenfunc sq_length;
251 binaryfunc sq_concat;
252 ssizeargfunc sq_repeat;
253 ssizeargfunc sq_item;
254 void *was_sq_slice;
255 ssizeobjargproc sq_ass_item;
256 void *was_sq_ass_slice;
257 objobjproc sq_contains;
Guido van Rossum50e9fb92006-08-17 05:42:55 +0000258
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000259 binaryfunc sq_inplace_concat;
260 ssizeargfunc sq_inplace_repeat;
Guido van Rossumcaa63801995-01-12 11:45:45 +0000261} PySequenceMethods;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000262
263typedef struct {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000264 lenfunc mp_length;
265 binaryfunc mp_subscript;
266 objobjargproc mp_ass_subscript;
Guido van Rossumcaa63801995-01-12 11:45:45 +0000267} PyMappingMethods;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000268
Tim Peters803526b2002-07-07 05:13:56 +0000269
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000270typedef struct {
271 getbufferproc bf_getbuffer;
272 releasebufferproc bf_releasebuffer;
Travis E. Oliphantb99f7622007-08-18 11:21:56 +0000273} PyBufferProcs;
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000274#endif /* Py_LIMITED_API */
Guido van Rossumfdf95dd1997-05-05 22:15:02 +0000275
Neil Schemenauerf6d1ea12002-04-12 01:57:06 +0000276typedef void (*freefunc)(void *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000277typedef void (*destructor)(PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000278#ifndef Py_LIMITED_API
279/* We can't provide a full compile-time check that limited-API
280 users won't implement tp_print. However, not defining printfunc
281 and making tp_print of a different function pointer type
282 should at least cause a warning in most cases. */
Tim Peters9ace6bc2000-07-08 00:32:04 +0000283typedef int (*printfunc)(PyObject *, FILE *, int);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000284#endif
Martin v. Löwis15e62742006-02-27 16:46:16 +0000285typedef PyObject *(*getattrfunc)(PyObject *, char *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000286typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
Martin v. Löwis15e62742006-02-27 16:46:16 +0000287typedef int (*setattrfunc)(PyObject *, char *, PyObject *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000288typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000289typedef PyObject *(*reprfunc)(PyObject *);
Benjamin Peterson8f67d082010-10-17 20:54:53 +0000290typedef Py_hash_t (*hashfunc)(PyObject *);
Guido van Rossum5f284ce2001-01-17 15:20:39 +0000291typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int);
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000292typedef PyObject *(*getiterfunc) (PyObject *);
Guido van Rossum213c7a62001-04-23 14:08:49 +0000293typedef PyObject *(*iternextfunc) (PyObject *);
Tim Peters6d6c1a32001-08-02 04:15:00 +0000294typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *);
295typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *);
296typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
297typedef PyObject *(*newfunc)(struct _typeobject *, PyObject *, PyObject *);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000298typedef PyObject *(*allocfunc)(struct _typeobject *, Py_ssize_t);
Guido van Rossumb6775db1994-08-01 11:34:53 +0000299
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000300#ifdef Py_LIMITED_API
301typedef struct _typeobject PyTypeObject; /* opaque */
302#else
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000303typedef struct _typeobject {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000304 PyObject_VAR_HEAD
305 const char *tp_name; /* For printing, in format "<module>.<name>" */
306 Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */
Tim Peters803526b2002-07-07 05:13:56 +0000307
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000308 /* Methods to implement standard operations */
Tim Peters803526b2002-07-07 05:13:56 +0000309
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000310 destructor tp_dealloc;
311 printfunc tp_print;
312 getattrfunc tp_getattr;
313 setattrfunc tp_setattr;
314 void *tp_reserved; /* formerly known as tp_compare */
315 reprfunc tp_repr;
Tim Peters803526b2002-07-07 05:13:56 +0000316
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000317 /* Method suites for standard classes */
Tim Peters803526b2002-07-07 05:13:56 +0000318
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000319 PyNumberMethods *tp_as_number;
320 PySequenceMethods *tp_as_sequence;
321 PyMappingMethods *tp_as_mapping;
Guido van Rossum9bfef441993-03-29 10:43:31 +0000322
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000323 /* More standard operations (here for binary compatibility) */
Guido van Rossum9bfef441993-03-29 10:43:31 +0000324
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000325 hashfunc tp_hash;
326 ternaryfunc tp_call;
327 reprfunc tp_str;
328 getattrofunc tp_getattro;
329 setattrofunc tp_setattro;
Guido van Rossum6fde3901995-01-07 10:32:04 +0000330
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000331 /* Functions to access object as input/output buffer */
332 PyBufferProcs *tp_as_buffer;
Tim Peters803526b2002-07-07 05:13:56 +0000333
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000334 /* Flags to define presence of optional/expanded features */
335 long tp_flags;
Guido van Rossum6fde3901995-01-07 10:32:04 +0000336
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000337 const char *tp_doc; /* Documentation string */
Guido van Rossum6fde3901995-01-07 10:32:04 +0000338
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000339 /* Assigned meaning in release 2.0 */
340 /* call function for all accessible objects */
341 traverseproc tp_traverse;
Tim Peters803526b2002-07-07 05:13:56 +0000342
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000343 /* delete references to contained objects */
344 inquiry tp_clear;
Jeremy Hylton8caad492000-06-23 14:18:11 +0000345
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000346 /* Assigned meaning in release 2.1 */
347 /* rich comparisons */
348 richcmpfunc tp_richcompare;
Guido van Rossum5f284ce2001-01-17 15:20:39 +0000349
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000350 /* weak reference enabler */
351 Py_ssize_t tp_weaklistoffset;
Guido van Rossuma9c2d7a1998-04-23 19:16:44 +0000352
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000353 /* Iterators */
354 getiterfunc tp_iter;
355 iternextfunc tp_iternext;
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000356
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000357 /* Attribute descriptor and subclassing stuff */
358 struct PyMethodDef *tp_methods;
359 struct PyMemberDef *tp_members;
360 struct PyGetSetDef *tp_getset;
361 struct _typeobject *tp_base;
362 PyObject *tp_dict;
363 descrgetfunc tp_descr_get;
364 descrsetfunc tp_descr_set;
365 Py_ssize_t tp_dictoffset;
366 initproc tp_init;
367 allocfunc tp_alloc;
368 newfunc tp_new;
369 freefunc tp_free; /* Low-level free-memory routine */
370 inquiry tp_is_gc; /* For PyObject_IS_GC */
371 PyObject *tp_bases;
372 PyObject *tp_mro; /* method resolution order */
373 PyObject *tp_cache;
374 PyObject *tp_subclasses;
375 PyObject *tp_weaklist;
376 destructor tp_del;
Tim Peters6d6c1a32001-08-02 04:15:00 +0000377
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000378 /* Type attribute cache version tag. Added in version 2.6 */
379 unsigned int tp_version_tag;
Christian Heimesa62da1d2008-01-12 19:39:10 +0000380
Sjoerd Mullendera9c3c221993-10-11 12:54:31 +0000381#ifdef COUNT_ALLOCS
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000382 /* these must be last and never explicitly initialized */
383 Py_ssize_t tp_allocs;
384 Py_ssize_t tp_frees;
385 Py_ssize_t tp_maxalloc;
386 struct _typeobject *tp_prev;
387 struct _typeobject *tp_next;
Sjoerd Mullendera9c3c221993-10-11 12:54:31 +0000388#endif
Guido van Rossumcaa63801995-01-12 11:45:45 +0000389} PyTypeObject;
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000390#endif
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000391
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000392typedef struct{
393 int slot; /* slot id, see below */
394 void *pfunc; /* function pointer */
395} PyType_Slot;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000396
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000397typedef struct{
398 const char* name;
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000399 int basicsize;
400 int itemsize;
401 int flags;
402 PyType_Slot *slots; /* terminated by slot==0. */
403} PyType_Spec;
404
405PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*);
406
407#ifndef Py_LIMITED_API
Guido van Rossume5c691a2003-03-07 15:13:17 +0000408/* The *real* layout of a type object when allocated on the heap */
409typedef struct _heaptypeobject {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000410 /* Note: there's a dependency on the order of these members
411 in slotptr() in typeobject.c . */
412 PyTypeObject ht_type;
413 PyNumberMethods as_number;
414 PyMappingMethods as_mapping;
415 PySequenceMethods as_sequence; /* as_sequence comes after as_mapping,
416 so that the mapping wins when both
417 the mapping and the sequence define
418 a given operator (e.g. __getitem__).
419 see add_operators() in typeobject.c . */
420 PyBufferProcs as_buffer;
421 PyObject *ht_name, *ht_slots;
422 /* here are optional user slots, followed by the members. */
Guido van Rossume5c691a2003-03-07 15:13:17 +0000423} PyHeapTypeObject;
424
425/* access macro to the members which are floating "behind" the object */
426#define PyHeapType_GET_MEMBERS(etype) \
Christian Heimes90aa7642007-12-19 02:45:37 +0000427 ((PyMemberDef *)(((char *)etype) + Py_TYPE(etype)->tp_basicsize))
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000428#endif
Guido van Rossume5c691a2003-03-07 15:13:17 +0000429
Tim Peters6d6c1a32001-08-02 04:15:00 +0000430/* Generic type check */
Mark Hammonda2905272002-07-29 13:42:14 +0000431PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *);
Tim Peters6d6c1a32001-08-02 04:15:00 +0000432#define PyObject_TypeCheck(ob, tp) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000433 (Py_TYPE(ob) == (tp) || PyType_IsSubtype(Py_TYPE(ob), (tp)))
Tim Peters6d6c1a32001-08-02 04:15:00 +0000434
Mark Hammonda2905272002-07-29 13:42:14 +0000435PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */
436PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */
437PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */
Tim Peters6d6c1a32001-08-02 04:15:00 +0000438
Martin v. Löwis738236d2011-02-05 20:35:29 +0000439PyAPI_FUNC(long) PyType_GetFlags(PyTypeObject*);
440
Thomas Wouters27d517b2007-02-25 20:39:11 +0000441#define PyType_Check(op) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000442 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS)
Christian Heimes90aa7642007-12-19 02:45:37 +0000443#define PyType_CheckExact(op) (Py_TYPE(op) == &PyType_Type)
Tim Peters6d6c1a32001-08-02 04:15:00 +0000444
Mark Hammonda2905272002-07-29 13:42:14 +0000445PyAPI_FUNC(int) PyType_Ready(PyTypeObject *);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000446PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t);
Mark Hammonda2905272002-07-29 13:42:14 +0000447PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000448 PyObject *, PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000449#ifndef Py_LIMITED_API
Mark Hammonda2905272002-07-29 13:42:14 +0000450PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *);
Benjamin Peterson224205f2009-05-08 03:25:19 +0000451PyAPI_FUNC(PyObject *) _PyObject_LookupSpecial(PyObject *, char *, PyObject **);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000452#endif
Christian Heimes26855632008-01-27 23:50:43 +0000453PyAPI_FUNC(unsigned int) PyType_ClearCache(void);
Georg Brandlf08a9dd2008-06-10 16:57:31 +0000454PyAPI_FUNC(void) PyType_Modified(PyTypeObject *);
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000455
Guido van Rossum3f5da241990-12-20 15:06:42 +0000456/* Generic operations on objects */
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000457#ifndef Py_LIMITED_API
Mark Hammonda2905272002-07-29 13:42:14 +0000458PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int);
Thomas Woutersb2137042007-02-01 18:02:27 +0000459PyAPI_FUNC(void) _Py_BreakPoint(void);
Mark Hammonda2905272002-07-29 13:42:14 +0000460PyAPI_FUNC(void) _PyObject_Dump(PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000461#endif
Mark Hammonda2905272002-07-29 13:42:14 +0000462PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
463PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
Georg Brandl559e5d72008-06-11 18:37:52 +0000464PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *);
Benjamin Petersonc15a0732008-08-26 16:46:47 +0000465PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *);
Mark Hammonda2905272002-07-29 13:42:14 +0000466PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
467PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
Jeremy Hyltonaf68c872005-12-10 18:50:16 +0000468PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *);
469PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *);
470PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *);
Mark Hammonda2905272002-07-29 13:42:14 +0000471PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
472PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
473PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000474#ifndef Py_LIMITED_API
Mark Hammonda2905272002-07-29 13:42:14 +0000475PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000476#endif
Raymond Hettinger1da1dbf2003-03-17 19:46:11 +0000477PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000478#ifndef Py_LIMITED_API
Amaury Forgeot d'Arcf343e012009-01-12 23:58:21 +0000479PyAPI_FUNC(PyObject *) _PyObject_NextNotImplemented(PyObject *);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000480#endif
Mark Hammonda2905272002-07-29 13:42:14 +0000481PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
482PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000483 PyObject *, PyObject *);
Benjamin Peterson8f67d082010-10-17 20:54:53 +0000484PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *);
485PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *);
Mark Hammonda2905272002-07-29 13:42:14 +0000486PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
487PyAPI_FUNC(int) PyObject_Not(PyObject *);
488PyAPI_FUNC(int) PyCallable_Check(PyObject *);
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000489
Mark Hammonda2905272002-07-29 13:42:14 +0000490PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
Fred Drake41deb1e2001-02-01 05:27:45 +0000491
Antoine Pitrou1a9a9d52010-08-28 18:17:03 +0000492/* Same as PyObject_Generic{Get,Set}Attr, but passing the attributes
493 dict as the last parameter. */
494PyAPI_FUNC(PyObject *)
495_PyObject_GenericGetAttrWithDict(PyObject *, PyObject *, PyObject *);
496PyAPI_FUNC(int)
497_PyObject_GenericSetAttrWithDict(PyObject *, PyObject *,
498 PyObject *, PyObject *);
499
Guido van Rossumab3b0342001-09-18 20:38:53 +0000500
Georg Brandl1a3284e2007-12-02 09:40:06 +0000501/* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a
502 list of strings. PyObject_Dir(NULL) is like builtins.dir(),
Tim Peters7eea37e2001-09-04 22:08:56 +0000503 returning the names of the current locals. In this case, if there are
504 no current locals, NULL is returned, and PyErr_Occurred() is false.
505*/
Mark Hammonda2905272002-07-29 13:42:14 +0000506PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
Tim Peters7eea37e2001-09-04 22:08:56 +0000507
508
Guido van Rossum26d4ac31998-04-10 22:32:24 +0000509/* Helpers for printing recursive container types */
Mark Hammonda2905272002-07-29 13:42:14 +0000510PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
511PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
Guido van Rossum26d4ac31998-04-10 22:32:24 +0000512
Fred Drake13634cf2000-06-29 19:17:04 +0000513/* Helpers for hash functions */
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000514#ifndef Py_LIMITED_API
Benjamin Peterson8f67d082010-10-17 20:54:53 +0000515PyAPI_FUNC(Py_hash_t) _Py_HashDouble(double);
516PyAPI_FUNC(Py_hash_t) _Py_HashPointer(void*);
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000517#endif
Fred Drake13634cf2000-06-29 19:17:04 +0000518
Jeremy Hylton483638c2001-02-01 20:20:45 +0000519/* Helper for passing objects to printf and the like */
Marc-André Lemburg4cc0f242008-08-07 18:54:33 +0000520#define PyObject_REPR(obj) _PyUnicode_AsString(PyObject_Repr(obj))
Jeremy Hylton483638c2001-02-01 20:20:45 +0000521
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000522/* Flag bits for printing: */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000523#define Py_PRINT_RAW 1 /* No string quotes etc. */
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000524
525/*
Tim Peters4be93d02002-07-07 19:59:50 +0000526`Type flags (tp_flags)
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000527
528These flags are used to extend the type structure in a backwards-compatible
529fashion. Extensions can use the flags to indicate (and test) when a given
530type structure contains a new feature. The Python core will use these when
531introducing new functionality between major revisions (to avoid mid-version
532changes in the PYTHON_API_VERSION).
533
534Arbitration of the flag bit positions will need to be coordinated among
535all extension writers who publically release their extensions (this will
536be fewer than you might expect!)..
537
Guido van Rossum3cf5b1e2006-07-27 21:53:35 +0000538Most flags were removed as of Python 3.0 to make room for new flags. (Some
539flags are not for backwards compatibility but to indicate the presence of an
540optional feature; these flags remain of course.)
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000541
542Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
543
544Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
545given type object has a specified feature.
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000546*/
547
Tim Peters6d6c1a32001-08-02 04:15:00 +0000548/* Set if the type object is dynamically allocated */
549#define Py_TPFLAGS_HEAPTYPE (1L<<9)
550
551/* Set if the type allows subclassing */
552#define Py_TPFLAGS_BASETYPE (1L<<10)
553
Guido van Rossum9b9c9722001-08-10 17:37:02 +0000554/* Set if the type is 'ready' -- fully initialized */
555#define Py_TPFLAGS_READY (1L<<12)
556
557/* Set while the type is being 'readied', to prevent recursive ready calls */
558#define Py_TPFLAGS_READYING (1L<<13)
559
Neil Schemenauer31ec1422001-08-29 23:46:35 +0000560/* Objects support garbage collection (see objimp.h) */
Neil Schemenauer31ec1422001-08-29 23:46:35 +0000561#define Py_TPFLAGS_HAVE_GC (1L<<14)
Neil Schemenauer31ec1422001-08-29 23:46:35 +0000562
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000563/* These two bits are preserved for Stackless Python, next after this is 17 */
Christian Tismer6695ba82003-05-20 15:14:31 +0000564#ifdef STACKLESS
Christian Tismer661a9e32003-05-23 12:47:36 +0000565#define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3L<<15)
Christian Tismer6695ba82003-05-20 15:14:31 +0000566#else
Christian Tismerc26ff412003-05-23 03:33:35 +0000567#define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
Christian Tismer6695ba82003-05-20 15:14:31 +0000568#endif
569
Christian Heimesa62da1d2008-01-12 19:39:10 +0000570/* Objects support type attribute cache */
571#define Py_TPFLAGS_HAVE_VERSION_TAG (1L<<18)
572#define Py_TPFLAGS_VALID_VERSION_TAG (1L<<19)
573
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000574/* Type is abstract and cannot be instantiated */
575#define Py_TPFLAGS_IS_ABSTRACT (1L<<20)
576
Thomas Wouters27d517b2007-02-25 20:39:11 +0000577/* These flags are used to determine if a type is a subclass. */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000578#define Py_TPFLAGS_INT_SUBCLASS (1L<<23)
579#define Py_TPFLAGS_LONG_SUBCLASS (1L<<24)
580#define Py_TPFLAGS_LIST_SUBCLASS (1L<<25)
581#define Py_TPFLAGS_TUPLE_SUBCLASS (1L<<26)
582#define Py_TPFLAGS_BYTES_SUBCLASS (1L<<27)
583#define Py_TPFLAGS_UNICODE_SUBCLASS (1L<<28)
584#define Py_TPFLAGS_DICT_SUBCLASS (1L<<29)
585#define Py_TPFLAGS_BASE_EXC_SUBCLASS (1L<<30)
586#define Py_TPFLAGS_TYPE_SUBCLASS (1L<<31)
Thomas Wouters27d517b2007-02-25 20:39:11 +0000587
Guido van Rossumbacca542001-01-24 22:13:48 +0000588#define Py_TPFLAGS_DEFAULT ( \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000589 Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
590 Py_TPFLAGS_HAVE_VERSION_TAG | \
591 0)
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000592
Martin v. Löwis738236d2011-02-05 20:35:29 +0000593#ifdef Py_LIMITED_API
594#define PyType_HasFeature(t,f) ((PyType_GetFlags(t) & (f)) != 0)
595#else
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000596#define PyType_HasFeature(t,f) (((t)->tp_flags & (f)) != 0)
Martin v. Löwis738236d2011-02-05 20:35:29 +0000597#endif
Thomas Wouters27d517b2007-02-25 20:39:11 +0000598#define PyType_FastSubclass(t,f) PyType_HasFeature(t,f)
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000599
600
601/*
Guido van Rossumcaa63801995-01-12 11:45:45 +0000602The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
Tim Peters4be93d02002-07-07 19:59:50 +0000603reference counts. Py_DECREF calls the object's deallocator function when
604the refcount falls to 0; for
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000605objects that don't contain references to other objects or heap memory
606this can be the standard function free(). Both macros can be used
Tim Peters4be93d02002-07-07 19:59:50 +0000607wherever a void expression is allowed. The argument must not be a
Benjamin Peterson2a691a82008-03-31 01:51:45 +0000608NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead.
Tim Peters4be93d02002-07-07 19:59:50 +0000609The macro _Py_NewReference(op) initialize reference counts to 1, and
610in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
611bookkeeping appropriate to the special build.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000612
613We assume that the reference count field can never overflow; this can
Tim Peters4be93d02002-07-07 19:59:50 +0000614be proven when the size of the field is the same as the pointer size, so
615we ignore the possibility. Provided a C int is at least 32 bits (which
616is implicitly assumed in many parts of this code), that's enough for
617about 2**31 references to an object.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000618
Tim Peters4be93d02002-07-07 19:59:50 +0000619XXX The following became out of date in Python 2.2, but I'm not sure
620XXX what the full truth is now. Certainly, heap-allocated type objects
621XXX can and should be deallocated.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000622Type objects should never be deallocated; the type pointer in an object
623is not considered to be a reference to the type object, to save
624complications in the deallocation function. (This is actually a
625decision that's up to the implementer of each new type so if you want,
626you can count such references to the type object.)
627
Guido van Rossumcaa63801995-01-12 11:45:45 +0000628*** WARNING*** The Py_DECREF macro must have a side-effect-free argument
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000629since it may evaluate its argument multiple times. (The alternative
630would be to mace it a proper function or assign it to a global temporary
631variable first, both of which are slower; and in a multi-threaded
632environment the global variable trick is not safe.)
633*/
634
Tim Peters34592512002-07-11 06:23:50 +0000635/* First define a pile of simple helper macros, one set per special
636 * build symbol. These either expand to the obvious things, or to
637 * nothing at all when the special mode isn't in effect. The main
638 * macros can later be defined just once then, yet expand to different
639 * things depending on which special build options are and aren't in effect.
640 * Trust me <wink>: while painful, this is 20x easier to understand than,
641 * e.g, defining _Py_NewReference five different times in a maze of nested
642 * #ifdefs (we used to do that -- it was impenetrable).
643 */
Tim Peters4be93d02002-07-07 19:59:50 +0000644#ifdef Py_REF_DEBUG
Neal Norwitz4281cef2006-03-04 19:58:13 +0000645PyAPI_DATA(Py_ssize_t) _Py_RefTotal;
Mark Hammonda2905272002-07-29 13:42:14 +0000646PyAPI_FUNC(void) _Py_NegativeRefcount(const char *fname,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000647 int lineno, PyObject *op);
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000648PyAPI_FUNC(PyObject *) _PyDict_Dummy(void);
649PyAPI_FUNC(PyObject *) _PySet_Dummy(void);
650PyAPI_FUNC(Py_ssize_t) _Py_GetRefTotal(void);
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000651#define _Py_INC_REFTOTAL _Py_RefTotal++
652#define _Py_DEC_REFTOTAL _Py_RefTotal--
653#define _Py_REF_DEBUG_COMMA ,
654#define _Py_CHECK_REFCNT(OP) \
655{ if (((PyObject*)OP)->ob_refcnt < 0) \
656 _Py_NegativeRefcount(__FILE__, __LINE__, \
657 (PyObject *)(OP)); \
Tim Peters7c321a82002-07-09 02:57:01 +0000658}
Tim Peters4be93d02002-07-07 19:59:50 +0000659#else
Tim Peters34592512002-07-11 06:23:50 +0000660#define _Py_INC_REFTOTAL
661#define _Py_DEC_REFTOTAL
662#define _Py_REF_DEBUG_COMMA
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000663#define _Py_CHECK_REFCNT(OP) /* a semicolon */;
Tim Peters57f4ddd2002-07-10 06:34:15 +0000664#endif /* Py_REF_DEBUG */
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000665
Sjoerd Mullendera9c3c221993-10-11 12:54:31 +0000666#ifdef COUNT_ALLOCS
Mark Hammonda2905272002-07-29 13:42:14 +0000667PyAPI_FUNC(void) inc_count(PyTypeObject *);
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000668PyAPI_FUNC(void) dec_count(PyTypeObject *);
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000669#define _Py_INC_TPALLOCS(OP) inc_count(Py_TYPE(OP))
670#define _Py_INC_TPFREES(OP) dec_count(Py_TYPE(OP))
671#define _Py_DEC_TPFREES(OP) Py_TYPE(OP)->tp_frees--
672#define _Py_COUNT_ALLOCS_COMMA ,
Sjoerd Mullendera9c3c221993-10-11 12:54:31 +0000673#else
Tim Peters34592512002-07-11 06:23:50 +0000674#define _Py_INC_TPALLOCS(OP)
675#define _Py_INC_TPFREES(OP)
676#define _Py_DEC_TPFREES(OP)
677#define _Py_COUNT_ALLOCS_COMMA
Tim Peters57f4ddd2002-07-10 06:34:15 +0000678#endif /* COUNT_ALLOCS */
Tim Peters4be93d02002-07-07 19:59:50 +0000679
680#ifdef Py_TRACE_REFS
681/* Py_TRACE_REFS is such major surgery that we call external routines. */
Mark Hammonda2905272002-07-29 13:42:14 +0000682PyAPI_FUNC(void) _Py_NewReference(PyObject *);
683PyAPI_FUNC(void) _Py_ForgetReference(PyObject *);
684PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
685PyAPI_FUNC(void) _Py_PrintReferences(FILE *);
Tim Peters269b2a62003-04-17 19:52:29 +0000686PyAPI_FUNC(void) _Py_PrintReferenceAddresses(FILE *);
Tim Peters7571a0f2003-03-23 17:52:28 +0000687PyAPI_FUNC(void) _Py_AddToAllObjects(PyObject *, int force);
Tim Peters4be93d02002-07-07 19:59:50 +0000688
689#else
690/* Without Py_TRACE_REFS, there's little enough to do that we expand code
691 * inline.
692 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000693#define _Py_NewReference(op) ( \
694 _Py_INC_TPALLOCS(op) _Py_COUNT_ALLOCS_COMMA \
695 _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \
696 Py_REFCNT(op) = 1)
Tim Peters4be93d02002-07-07 19:59:50 +0000697
Tim Peters34592512002-07-11 06:23:50 +0000698#define _Py_ForgetReference(op) _Py_INC_TPFREES(op)
Tim Peters4be93d02002-07-07 19:59:50 +0000699
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000700#ifdef Py_LIMITED_API
701PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
702#else
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000703#define _Py_Dealloc(op) ( \
704 _Py_INC_TPFREES(op) _Py_COUNT_ALLOCS_COMMA \
705 (*Py_TYPE(op)->tp_dealloc)((PyObject *)(op)))
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000706#endif
Guido van Rossum60be1db1996-05-22 16:33:22 +0000707#endif /* !Py_TRACE_REFS */
708
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000709#define Py_INCREF(op) ( \
710 _Py_INC_REFTOTAL _Py_REF_DEBUG_COMMA \
711 ((PyObject*)(op))->ob_refcnt++)
Tim Peters4be93d02002-07-07 19:59:50 +0000712
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000713#define Py_DECREF(op) \
714 do { \
715 if (_Py_DEC_REFTOTAL _Py_REF_DEBUG_COMMA \
716 --((PyObject*)(op))->ob_refcnt != 0) \
717 _Py_CHECK_REFCNT(op) \
718 else \
719 _Py_Dealloc((PyObject *)(op)); \
720 } while (0)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000721
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000722/* Safely decref `op` and set `op` to NULL, especially useful in tp_clear
723 * and tp_dealloc implementatons.
724 *
725 * Note that "the obvious" code can be deadly:
726 *
727 * Py_XDECREF(op);
728 * op = NULL;
729 *
730 * Typically, `op` is something like self->containee, and `self` is done
731 * using its `containee` member. In the code sequence above, suppose
732 * `containee` is non-NULL with a refcount of 1. Its refcount falls to
733 * 0 on the first line, which can trigger an arbitrary amount of code,
734 * possibly including finalizers (like __del__ methods or weakref callbacks)
735 * coded in Python, which in turn can release the GIL and allow other threads
736 * to run, etc. Such code may even invoke methods of `self` again, or cause
737 * cyclic gc to trigger, but-- oops! --self->containee still points to the
738 * object being torn down, and it may be in an insane state while being torn
739 * down. This has in fact been a rich historic source of miserable (rare &
740 * hard-to-diagnose) segfaulting (and other) bugs.
741 *
742 * The safe way is:
743 *
744 * Py_CLEAR(op);
745 *
746 * That arranges to set `op` to NULL _before_ decref'ing, so that any code
747 * triggered as a side-effect of `op` getting torn down no longer believes
748 * `op` points to a valid object.
749 *
750 * There are cases where it's safe to use the naive code, but they're brittle.
751 * For example, if `op` points to a Python integer, you know that destroying
752 * one of those can't cause problems -- but in part that relies on that
753 * Python integers aren't currently weakly referencable. Best practice is
754 * to use Py_CLEAR() even if you can't think of a reason for why you need to.
755 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000756#define Py_CLEAR(op) \
757 do { \
758 if (op) { \
759 PyObject *_py_tmp = (PyObject *)(op); \
760 (op) = NULL; \
761 Py_DECREF(_py_tmp); \
762 } \
763 } while (0)
Jim Fulton8c5aeaa2004-07-14 19:07:35 +0000764
Guido van Rossum3f5da241990-12-20 15:06:42 +0000765/* Macros to use in case the object pointer may be NULL: */
Matthias Klose091c7b12009-04-07 13:24:27 +0000766#define Py_XINCREF(op) do { if ((op) == NULL) ; else Py_INCREF(op); } while (0)
767#define Py_XDECREF(op) do { if ((op) == NULL) ; else Py_DECREF(op); } while (0)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000768
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000769/*
Thomas Heller1328b522004-04-22 17:23:49 +0000770These are provided as conveniences to Python runtime embedders, so that
771they can have object code that is not dependent on Python compilation flags.
772*/
773PyAPI_FUNC(void) Py_IncRef(PyObject *);
774PyAPI_FUNC(void) Py_DecRef(PyObject *);
775
776/*
Guido van Rossumcaa63801995-01-12 11:45:45 +0000777_Py_NoneStruct is an object of undefined type which can be used in contexts
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000778where NULL (nil) is not suitable (since NULL often means 'error').
779
Guido van Rossumcaa63801995-01-12 11:45:45 +0000780Don't forget to apply Py_INCREF() when returning this value!!!
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000781*/
Mark Hammonda2905272002-07-29 13:42:14 +0000782PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
Guido van Rossumcaa63801995-01-12 11:45:45 +0000783#define Py_None (&_Py_NoneStruct)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000784
Brett Cannond05235e2003-10-19 21:19:40 +0000785/* Macro for returning Py_None from a function */
Tim Peters5980ff22004-07-22 01:46:43 +0000786#define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None
Brett Cannond05235e2003-10-19 21:19:40 +0000787
Neil Schemenauera7ed6942001-01-04 01:31:50 +0000788/*
789Py_NotImplemented is a singleton used to signal that an operation is
790not implemented for a given type combination.
791*/
Mark Hammonda2905272002-07-29 13:42:14 +0000792PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
Neil Schemenauera7ed6942001-01-04 01:31:50 +0000793#define Py_NotImplemented (&_Py_NotImplementedStruct)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000794
Guido van Rossum5f284ce2001-01-17 15:20:39 +0000795/* Rich comparison opcodes */
796#define Py_LT 0
797#define Py_LE 1
798#define Py_EQ 2
799#define Py_NE 3
800#define Py_GT 4
801#define Py_GE 5
802
Tim Petersf4aca752004-09-23 02:39:37 +0000803/* Maps Py_LT to Py_GT, ..., Py_GE to Py_LE.
804 * Defined in object.c.
805 */
806PyAPI_DATA(int) _Py_SwappedOp[];
807
Guido van Rossumb6775db1994-08-01 11:34:53 +0000808
809/*
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000810More conventions
811================
812
813Argument Checking
814-----------------
815
816Functions that take objects as arguments normally don't check for nil
817arguments, but they do check the type of the argument, and return an
818error if the function doesn't apply to the type.
819
820Failure Modes
821-------------
822
823Functions may fail for a variety of reasons, including running out of
Guido van Rossum3f5da241990-12-20 15:06:42 +0000824memory. This is communicated to the caller in two ways: an error string
825is set (see errors.h), and the function result differs: functions that
826normally return a pointer return NULL for failure, functions returning
827an integer return -1 (which could be a legal return value too!), and
828other functions return 0 for success and -1 for failure.
Tim Peters4be93d02002-07-07 19:59:50 +0000829Callers should always check for errors before using the result. If
830an error was set, the caller must either explicitly clear it, or pass
831the error on to its caller.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000832
833Reference Counts
834----------------
835
836It takes a while to get used to the proper usage of reference counts.
837
838Functions that create an object set the reference count to 1; such new
Guido van Rossumcaa63801995-01-12 11:45:45 +0000839objects must be stored somewhere or destroyed again with Py_DECREF().
Alex Martelli721b7762003-11-09 16:38:39 +0000840Some functions that 'store' objects, such as PyTuple_SetItem() and
841PyList_SetItem(),
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000842don't increment the reference count of the object, since the most
843frequent use is to store a fresh object. Functions that 'retrieve'
Alex Martelli721b7762003-11-09 16:38:39 +0000844objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
Guido van Rossumcaa63801995-01-12 11:45:45 +0000845don't increment
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000846the reference count, since most frequently the object is only looked at
847quickly. Thus, to retrieve an object and store it again, the caller
Guido van Rossumcaa63801995-01-12 11:45:45 +0000848must call Py_INCREF() explicitly.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000849
Alex Martelli721b7762003-11-09 16:38:39 +0000850NOTE: functions that 'consume' a reference count, like
851PyList_SetItem(), consume the reference even if the object wasn't
852successfully stored, to simplify error handling.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000853
854It seems attractive to make other functions that take an object as
Alex Martelli721b7762003-11-09 16:38:39 +0000855argument consume a reference count; however, this may quickly get
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000856confusing (even the current practice is already confusing). Consider
Guido van Rossumcaa63801995-01-12 11:45:45 +0000857it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000858times.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000859*/
Guido van Rossuma3309961993-07-28 09:05:47 +0000860
Guido van Rossumd724b232000-03-13 16:01:29 +0000861
Tim Peters803526b2002-07-07 05:13:56 +0000862/* Trashcan mechanism, thanks to Christian Tismer.
Guido van Rossumd724b232000-03-13 16:01:29 +0000863
Tim Peters803526b2002-07-07 05:13:56 +0000864When deallocating a container object, it's possible to trigger an unbounded
865chain of deallocations, as each Py_DECREF in turn drops the refcount on "the
866next" object in the chain to 0. This can easily lead to stack faults, and
867especially in threads (which typically have less stack space to work with).
Guido van Rossumd724b232000-03-13 16:01:29 +0000868
Tim Peters803526b2002-07-07 05:13:56 +0000869A container object that participates in cyclic gc can avoid this by
870bracketing the body of its tp_dealloc function with a pair of macros:
Guido van Rossume92e6102000-04-24 15:40:53 +0000871
Tim Peters803526b2002-07-07 05:13:56 +0000872static void
873mytype_dealloc(mytype *p)
874{
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000875 ... declarations go here ...
Tim Peters803526b2002-07-07 05:13:56 +0000876
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000877 PyObject_GC_UnTrack(p); // must untrack first
878 Py_TRASHCAN_SAFE_BEGIN(p)
879 ... The body of the deallocator goes here, including all calls ...
880 ... to Py_DECREF on contained objects. ...
881 Py_TRASHCAN_SAFE_END(p)
Tim Peters803526b2002-07-07 05:13:56 +0000882}
883
Tim Peters808eb592002-08-07 20:53:05 +0000884CAUTION: Never return from the middle of the body! If the body needs to
885"get out early", put a label immediately before the Py_TRASHCAN_SAFE_END
886call, and goto it. Else the call-depth counter (see below) will stay
887above 0 forever, and the trashcan will never get emptied.
888
Tim Peters803526b2002-07-07 05:13:56 +0000889How it works: The BEGIN macro increments a call-depth counter. So long
890as this counter is small, the body of the deallocator is run directly without
891further ado. But if the counter gets large, it instead adds p to a list of
892objects to be deallocated later, skips the body of the deallocator, and
893resumes execution after the END macro. The tp_dealloc routine then returns
894without deallocating anything (and so unbounded call-stack depth is avoided).
895
896When the call stack finishes unwinding again, code generated by the END macro
897notices this, and calls another routine to deallocate all the objects that
898may have been added to the list of deferred deallocations. In effect, a
899chain of N deallocations is broken into N / PyTrash_UNWIND_LEVEL pieces,
900with the call stack never exceeding a depth of PyTrash_UNWIND_LEVEL.
Guido van Rossumd724b232000-03-13 16:01:29 +0000901*/
902
Mark Hammonda2905272002-07-29 13:42:14 +0000903PyAPI_FUNC(void) _PyTrash_deposit_object(PyObject*);
904PyAPI_FUNC(void) _PyTrash_destroy_chain(void);
905PyAPI_DATA(int) _PyTrash_delete_nesting;
906PyAPI_DATA(PyObject *) _PyTrash_delete_later;
Tim Peters803526b2002-07-07 05:13:56 +0000907
Guido van Rossumd724b232000-03-13 16:01:29 +0000908#define PyTrash_UNWIND_LEVEL 50
909
910#define Py_TRASHCAN_SAFE_BEGIN(op) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000911 if (_PyTrash_delete_nesting < PyTrash_UNWIND_LEVEL) { \
912 ++_PyTrash_delete_nesting;
913 /* The body of the deallocator is here. */
Guido van Rossumd724b232000-03-13 16:01:29 +0000914#define Py_TRASHCAN_SAFE_END(op) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000915 --_PyTrash_delete_nesting; \
916 if (_PyTrash_delete_later && _PyTrash_delete_nesting <= 0) \
917 _PyTrash_destroy_chain(); \
918 } \
919 else \
920 _PyTrash_deposit_object((PyObject*)op);
Guido van Rossume92e6102000-04-24 15:40:53 +0000921
Guido van Rossuma3309961993-07-28 09:05:47 +0000922#ifdef __cplusplus
923}
924#endif
925#endif /* !Py_OBJECT_H */