blob: e7e9c1b8ed752d72daaf7603b7a0b17b1f380637 [file] [log] [blame]
Guido van Rossuma3309961993-07-28 09:05:47 +00001#ifndef Py_OBJECT_H
2#define Py_OBJECT_H
Victor Stinner6279c1c2018-10-25 15:54:13 +02003
Guido van Rossuma3309961993-07-28 09:05:47 +00004#ifdef __cplusplus
5extern "C" {
6#endif
7
Guido van Rossumf70e43a1991-02-19 12:39:46 +00008
Guido van Rossum85a5fbb1990-10-14 12:07:46 +00009/* Object and type object interface */
10
11/*
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000012Objects are structures allocated on the heap. Special rules apply to
13the use of objects to ensure they are properly garbage-collected.
14Objects are never allocated statically or on the stack; they must be
15accessed through special macros and functions only. (Type objects are
16exceptions to the first rule; the standard types are represented by
Tim Peters4be93d02002-07-07 19:59:50 +000017statically initialized type objects, although work on type/class unification
18for Python 2.2 made it possible to have heap-allocated type objects too).
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000019
20An object has a 'reference count' that is increased or decreased when a
21pointer to the object is copied or deleted; when the reference count
22reaches zero there are no references to the object left and it can be
23removed from the heap.
24
25An object has a 'type' that determines what it represents and what kind
26of data it contains. An object's type is fixed when it is created.
27Types themselves are represented as objects; an object contains a
28pointer to the corresponding type object. The type itself has a type
29pointer pointing to the object representing the type 'type', which
30contains a pointer to itself!).
31
32Objects do not float around in memory; once allocated an object keeps
33the same size and address. Objects that must hold variable-size data
34can contain pointers to variable-size parts of the object. Not all
35objects of the same type have the same size; but the size cannot change
36after allocation. (These restrictions are made so a reference to an
37object can be simply a pointer -- moving an object would require
38updating all the pointers, and changing an object's size would require
39moving it if there was another object right next to it.)
40
Guido van Rossumcaa63801995-01-12 11:45:45 +000041Objects are always accessed through pointers of the type 'PyObject *'.
42The type 'PyObject' is a structure that only contains the reference count
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000043and the type pointer. The actual memory allocated for an object
44contains other data that can only be accessed after casting the pointer
45to a pointer to a longer structure type. This longer type must start
Guido van Rossumcaa63801995-01-12 11:45:45 +000046with the reference count and type fields; the macro PyObject_HEAD should be
Thomas Wouters7e474022000-07-16 12:04:32 +000047used for this (to accommodate for future changes). The implementation
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000048of a particular object type can cast the object pointer to the proper
49type and back.
50
51A standard interface exists for objects that contain an array of items
52whose size is determined when the object is allocated.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000053*/
54
Victor Stinnerf4e47032019-04-25 00:56:28 +020055/* Py_DEBUG implies Py_REF_DEBUG. */
56#if defined(Py_DEBUG) && !defined(Py_REF_DEBUG)
Tim Peters4be93d02002-07-07 19:59:50 +000057#define Py_REF_DEBUG
58#endif
Guido van Rossum85a5fbb1990-10-14 12:07:46 +000059
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000060#if defined(Py_LIMITED_API) && defined(Py_REF_DEBUG)
61#error Py_LIMITED_API is incompatible with Py_DEBUG, Py_TRACE_REFS, and Py_REF_DEBUG
62#endif
63
Victor Stinner0e4e7352020-02-05 15:10:39 +010064/* PyTypeObject structure is defined in cpython/object.h.
65 In Py_LIMITED_API, PyTypeObject is an opaque structure. */
66typedef struct _typeobject PyTypeObject;
Nick Coghland6009512014-11-20 21:39:37 +100067
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;
Victor Stinner0e4e7352020-02-05 15:10:39 +0100108 PyTypeObject *ob_type;
Guido van Rossumcaa63801995-01-12 11:45:45 +0000109} PyObject;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000110
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100111/* Cast argument to PyObject* type. */
112#define _PyObject_CAST(op) ((PyObject*)(op))
113
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000114typedef struct {
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000115 PyObject ob_base;
116 Py_ssize_t ob_size; /* Number of items in variable part */
Guido van Rossumd0c87ee1997-05-15 21:31:03 +0000117} PyVarObject;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000118
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100119/* Cast argument to PyVarObject* type. */
120#define _PyVarObject_CAST(op) ((PyVarObject*)(op))
121
122#define Py_REFCNT(ob) (_PyObject_CAST(ob)->ob_refcnt)
123#define Py_TYPE(ob) (_PyObject_CAST(ob)->ob_type)
124#define Py_SIZE(ob) (_PyVarObject_CAST(ob)->ob_size)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000125
126/*
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000127Type objects contain a string containing the type name (to help somewhat
Tim Peters4be93d02002-07-07 19:59:50 +0000128in debugging), the allocation parameters (see PyObject_New() and
129PyObject_NewVar()),
130and methods for accessing objects of the type. Methods are optional, a
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000131nil pointer meaning that particular kind of access is not available for
Guido van Rossumcaa63801995-01-12 11:45:45 +0000132this type. The Py_DECREF() macro uses the tp_dealloc method without
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000133checking for a nil pointer; it should always be implemented except if
134the implementation can guarantee that the reference count will never
Tim Peters4be93d02002-07-07 19:59:50 +0000135reach zero (e.g., for statically allocated type objects).
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000136
137NB: the methods for certain type groups are now contained in separate
138method blocks.
139*/
140
Tim Peters9ace6bc2000-07-08 00:32:04 +0000141typedef PyObject * (*unaryfunc)(PyObject *);
142typedef PyObject * (*binaryfunc)(PyObject *, PyObject *);
143typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *);
144typedef int (*inquiry)(PyObject *);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000145typedef Py_ssize_t (*lenfunc)(PyObject *);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000146typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t);
147typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000148typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *);
149typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000150typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *);
Martin v. Löwis18e16552006-02-15 17:27:45 +0000151
Tim Peters9ace6bc2000-07-08 00:32:04 +0000152typedef int (*objobjproc)(PyObject *, PyObject *);
153typedef int (*visitproc)(PyObject *, void *);
154typedef int (*traverseproc)(PyObject *, visitproc, void *);
Guido van Rossumb6775db1994-08-01 11:34:53 +0000155
Guido van Rossumfdf95dd1997-05-05 22:15:02 +0000156
Neil Schemenauerf6d1ea12002-04-12 01:57:06 +0000157typedef void (*freefunc)(void *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000158typedef void (*destructor)(PyObject *);
Martin v. Löwis15e62742006-02-27 16:46:16 +0000159typedef PyObject *(*getattrfunc)(PyObject *, char *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000160typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
Martin v. Löwis15e62742006-02-27 16:46:16 +0000161typedef int (*setattrfunc)(PyObject *, char *, PyObject *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000162typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *);
Tim Peters9ace6bc2000-07-08 00:32:04 +0000163typedef PyObject *(*reprfunc)(PyObject *);
Benjamin Peterson8f67d082010-10-17 20:54:53 +0000164typedef Py_hash_t (*hashfunc)(PyObject *);
Guido van Rossum5f284ce2001-01-17 15:20:39 +0000165typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int);
Guido van Rossum59d1d2b2001-04-20 19:13:02 +0000166typedef PyObject *(*getiterfunc) (PyObject *);
Guido van Rossum213c7a62001-04-23 14:08:49 +0000167typedef PyObject *(*iternextfunc) (PyObject *);
Tim Peters6d6c1a32001-08-02 04:15:00 +0000168typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *);
169typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *);
170typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
Victor Stinner0e4e7352020-02-05 15:10:39 +0100171typedef PyObject *(*newfunc)(PyTypeObject *, PyObject *, PyObject *);
172typedef PyObject *(*allocfunc)(PyTypeObject *, Py_ssize_t);
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000173
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000174typedef struct{
175 int slot; /* slot id, see below */
176 void *pfunc; /* function pointer */
177} PyType_Slot;
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000178
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000179typedef struct{
180 const char* name;
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000181 int basicsize;
182 int itemsize;
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100183 unsigned int flags;
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000184 PyType_Slot *slots; /* terminated by slot==0. */
185} PyType_Spec;
186
187PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*);
Martin v. Löwis9c564092012-06-23 23:20:45 +0200188#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
189PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*);
190#endif
Martin v. Löwisca7b0462014-02-04 09:33:05 +0100191#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000
Victor Stinner0e4e7352020-02-05 15:10:39 +0100192PyAPI_FUNC(void*) PyType_GetSlot(PyTypeObject*, int);
Martin v. Löwisca7b0462014-02-04 09:33:05 +0100193#endif
Martin v. Löwis4d0d4712010-12-03 20:14:31 +0000194
Tim Peters6d6c1a32001-08-02 04:15:00 +0000195/* Generic type check */
Victor Stinner0e4e7352020-02-05 15:10:39 +0100196PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *);
Tim Peters6d6c1a32001-08-02 04:15:00 +0000197#define PyObject_TypeCheck(ob, tp) \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000198 (Py_TYPE(ob) == (tp) || PyType_IsSubtype(Py_TYPE(ob), (tp)))
Tim Peters6d6c1a32001-08-02 04:15:00 +0000199
Victor Stinner0e4e7352020-02-05 15:10:39 +0100200PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */
201PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */
202PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */
Tim Peters6d6c1a32001-08-02 04:15:00 +0000203
Victor Stinner0e4e7352020-02-05 15:10:39 +0100204PyAPI_FUNC(unsigned long) PyType_GetFlags(PyTypeObject*);
Martin v. Löwis738236d2011-02-05 20:35:29 +0000205
Victor Stinner0e4e7352020-02-05 15:10:39 +0100206PyAPI_FUNC(int) PyType_Ready(PyTypeObject *);
207PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t);
208PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *,
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000209 PyObject *, PyObject *);
Christian Heimes26855632008-01-27 23:50:43 +0000210PyAPI_FUNC(unsigned int) PyType_ClearCache(void);
Victor Stinner0e4e7352020-02-05 15:10:39 +0100211PyAPI_FUNC(void) PyType_Modified(PyTypeObject *);
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000212
Guido van Rossum3f5da241990-12-20 15:06:42 +0000213/* Generic operations on objects */
Mark Hammonda2905272002-07-29 13:42:14 +0000214PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
215PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
Georg Brandl559e5d72008-06-11 18:37:52 +0000216PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *);
Benjamin Petersonc15a0732008-08-26 16:46:47 +0000217PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *);
Mark Hammonda2905272002-07-29 13:42:14 +0000218PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
219PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
Jeremy Hyltonaf68c872005-12-10 18:50:16 +0000220PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *);
221PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *);
222PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *);
Mark Hammonda2905272002-07-29 13:42:14 +0000223PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
224PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
225PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
Raymond Hettinger1da1dbf2003-03-17 19:46:11 +0000226PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *);
Mark Hammonda2905272002-07-29 13:42:14 +0000227PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
Victor Stinnerf58bd7c2020-02-05 13:12:19 +0100228PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, PyObject *, PyObject *);
Serhiy Storchaka34d0ac82016-12-27 14:57:39 +0200229#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
Benjamin Peterson8eb12692012-02-19 19:59:10 -0500230PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *);
Serhiy Storchaka34d0ac82016-12-27 14:57:39 +0200231#endif
Benjamin Peterson8f67d082010-10-17 20:54:53 +0000232PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *);
233PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *);
Mark Hammonda2905272002-07-29 13:42:14 +0000234PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
235PyAPI_FUNC(int) PyObject_Not(PyObject *);
236PyAPI_FUNC(int) PyCallable_Check(PyObject *);
Mark Hammonda2905272002-07-29 13:42:14 +0000237PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
Guido van Rossumab3b0342001-09-18 20:38:53 +0000238
Georg Brandl1a3284e2007-12-02 09:40:06 +0000239/* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a
240 list of strings. PyObject_Dir(NULL) is like builtins.dir(),
Tim Peters7eea37e2001-09-04 22:08:56 +0000241 returning the names of the current locals. In this case, if there are
242 no current locals, NULL is returned, and PyErr_Occurred() is false.
243*/
Mark Hammonda2905272002-07-29 13:42:14 +0000244PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
Tim Peters7eea37e2001-09-04 22:08:56 +0000245
246
Guido van Rossum26d4ac31998-04-10 22:32:24 +0000247/* Helpers for printing recursive container types */
Mark Hammonda2905272002-07-29 13:42:14 +0000248PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
249PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
Guido van Rossum26d4ac31998-04-10 22:32:24 +0000250
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000251/* Flag bits for printing: */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000252#define Py_PRINT_RAW 1 /* No string quotes etc. */
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000253
254/*
Antoine Pitrouada319b2019-05-29 22:12:38 +0200255Type flags (tp_flags)
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000256
Antoine Pitrouada319b2019-05-29 22:12:38 +0200257These flags are used to change expected features and behavior for a
258particular type.
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000259
260Arbitration of the flag bit positions will need to be coordinated among
luzpaza5293b42017-11-05 07:37:50 -0600261all extension writers who publicly release their extensions (this will
Antoine Pitrouada319b2019-05-29 22:12:38 +0200262be fewer than you might expect!).
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000263
Guido van Rossum3cf5b1e2006-07-27 21:53:35 +0000264Most flags were removed as of Python 3.0 to make room for new flags. (Some
265flags are not for backwards compatibility but to indicate the presence of an
266optional feature; these flags remain of course.)
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000267
268Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
269
270Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
271given type object has a specified feature.
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000272*/
273
Tim Peters6d6c1a32001-08-02 04:15:00 +0000274/* Set if the type object is dynamically allocated */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100275#define Py_TPFLAGS_HEAPTYPE (1UL << 9)
Tim Peters6d6c1a32001-08-02 04:15:00 +0000276
277/* Set if the type allows subclassing */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100278#define Py_TPFLAGS_BASETYPE (1UL << 10)
Tim Peters6d6c1a32001-08-02 04:15:00 +0000279
Jeroen Demeyeraacc77f2019-05-29 20:31:52 +0200280/* Set if the type implements the vectorcall protocol (PEP 590) */
281#ifndef Py_LIMITED_API
282#define _Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11)
283#endif
284
Guido van Rossum9b9c9722001-08-10 17:37:02 +0000285/* Set if the type is 'ready' -- fully initialized */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100286#define Py_TPFLAGS_READY (1UL << 12)
Guido van Rossum9b9c9722001-08-10 17:37:02 +0000287
288/* Set while the type is being 'readied', to prevent recursive ready calls */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100289#define Py_TPFLAGS_READYING (1UL << 13)
Guido van Rossum9b9c9722001-08-10 17:37:02 +0000290
Antoine Pitrouada319b2019-05-29 22:12:38 +0200291/* Objects support garbage collection (see objimpl.h) */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100292#define Py_TPFLAGS_HAVE_GC (1UL << 14)
Neil Schemenauer31ec1422001-08-29 23:46:35 +0000293
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000294/* These two bits are preserved for Stackless Python, next after this is 17 */
Christian Tismer6695ba82003-05-20 15:14:31 +0000295#ifdef STACKLESS
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100296#define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15)
Christian Tismer6695ba82003-05-20 15:14:31 +0000297#else
Christian Tismerc26ff412003-05-23 03:33:35 +0000298#define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
Christian Tismer6695ba82003-05-20 15:14:31 +0000299#endif
300
Jeroen Demeyereb65e242019-05-28 14:42:53 +0200301/* Objects behave like an unbound method */
302#define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17)
303
Christian Heimesa62da1d2008-01-12 19:39:10 +0000304/* Objects support type attribute cache */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100305#define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18)
306#define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19)
Christian Heimesa62da1d2008-01-12 19:39:10 +0000307
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000308/* Type is abstract and cannot be instantiated */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100309#define Py_TPFLAGS_IS_ABSTRACT (1UL << 20)
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000310
Thomas Wouters27d517b2007-02-25 20:39:11 +0000311/* These flags are used to determine if a type is a subclass. */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100312#define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24)
313#define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25)
314#define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26)
315#define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27)
316#define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28)
317#define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29)
318#define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30)
319#define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31)
Thomas Wouters27d517b2007-02-25 20:39:11 +0000320
Guido van Rossumbacca542001-01-24 22:13:48 +0000321#define Py_TPFLAGS_DEFAULT ( \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000322 Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
323 Py_TPFLAGS_HAVE_VERSION_TAG | \
324 0)
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000325
Antoine Pitrou796564c2013-07-30 19:59:21 +0200326/* NOTE: The following flags reuse lower bits (removed as part of the
327 * Python 3.0 transition). */
328
Hansraj Das10e5c662019-07-06 03:07:15 +0530329/* The following flag is kept for compatibility. Starting with 3.8,
330 * binary compatibility of C extensions across feature releases of
Antoine Pitrouada319b2019-05-29 22:12:38 +0200331 * Python is not supported anymore, except when using the stable ABI.
332 */
333
Antoine Pitrou796564c2013-07-30 19:59:21 +0200334/* Type structure has tp_finalize member (3.4) */
335#define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0)
336
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000337
338/*
Guido van Rossumcaa63801995-01-12 11:45:45 +0000339The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
Tim Peters4be93d02002-07-07 19:59:50 +0000340reference counts. Py_DECREF calls the object's deallocator function when
341the refcount falls to 0; for
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000342objects that don't contain references to other objects or heap memory
343this can be the standard function free(). Both macros can be used
Tim Peters4be93d02002-07-07 19:59:50 +0000344wherever a void expression is allowed. The argument must not be a
Benjamin Peterson2a691a82008-03-31 01:51:45 +0000345NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead.
Tim Peters4be93d02002-07-07 19:59:50 +0000346The macro _Py_NewReference(op) initialize reference counts to 1, and
347in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
348bookkeeping appropriate to the special build.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000349
350We assume that the reference count field can never overflow; this can
Tim Peters4be93d02002-07-07 19:59:50 +0000351be proven when the size of the field is the same as the pointer size, so
352we ignore the possibility. Provided a C int is at least 32 bits (which
353is implicitly assumed in many parts of this code), that's enough for
354about 2**31 references to an object.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000355
Tim Peters4be93d02002-07-07 19:59:50 +0000356XXX The following became out of date in Python 2.2, but I'm not sure
357XXX what the full truth is now. Certainly, heap-allocated type objects
358XXX can and should be deallocated.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000359Type objects should never be deallocated; the type pointer in an object
360is not considered to be a reference to the type object, to save
361complications in the deallocation function. (This is actually a
362decision that's up to the implementer of each new type so if you want,
363you can count such references to the type object.)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000364*/
365
Tim Peters4be93d02002-07-07 19:59:50 +0000366#ifdef Py_REF_DEBUG
Neal Norwitz4281cef2006-03-04 19:58:13 +0000367PyAPI_DATA(Py_ssize_t) _Py_RefTotal;
Victor Stinner18618e652018-10-25 17:28:11 +0200368PyAPI_FUNC(void) _Py_NegativeRefcount(const char *filename, int lineno,
369 PyObject *op);
Tim Peters57f4ddd2002-07-10 06:34:15 +0000370#endif /* Py_REF_DEBUG */
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000371
Victor Stinner3c09dca2018-10-30 14:48:26 +0100372PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
373
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100374static inline void _Py_INCREF(PyObject *op)
375{
Victor Stinner49932fe2020-02-03 17:55:05 +0100376#ifdef Py_REF_DEBUG
377 _Py_RefTotal++;
378#endif
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100379 op->ob_refcnt++;
380}
381
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100382#define Py_INCREF(op) _Py_INCREF(_PyObject_CAST(op))
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100383
Victor Stinnerf3a0a6b2020-01-08 21:03:45 +0100384static inline void _Py_DECREF(
385#ifdef Py_REF_DEBUG
386 const char *filename, int lineno,
387#endif
388 PyObject *op)
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100389{
Victor Stinner49932fe2020-02-03 17:55:05 +0100390#ifdef Py_REF_DEBUG
391 _Py_RefTotal--;
392#endif
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100393 if (--op->ob_refcnt != 0) {
394#ifdef Py_REF_DEBUG
395 if (op->ob_refcnt < 0) {
396 _Py_NegativeRefcount(filename, lineno, op);
397 }
398#endif
399 }
400 else {
401 _Py_Dealloc(op);
402 }
403}
404
Victor Stinnerf3a0a6b2020-01-08 21:03:45 +0100405#ifdef Py_REF_DEBUG
406# define Py_DECREF(op) _Py_DECREF(__FILE__, __LINE__, _PyObject_CAST(op))
407#else
408# define Py_DECREF(op) _Py_DECREF(_PyObject_CAST(op))
409#endif
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100410
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000411
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000412/* Safely decref `op` and set `op` to NULL, especially useful in tp_clear
Berker Peksag4882cac2015-04-14 09:30:01 +0300413 * and tp_dealloc implementations.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000414 *
415 * Note that "the obvious" code can be deadly:
416 *
417 * Py_XDECREF(op);
418 * op = NULL;
419 *
420 * Typically, `op` is something like self->containee, and `self` is done
421 * using its `containee` member. In the code sequence above, suppose
422 * `containee` is non-NULL with a refcount of 1. Its refcount falls to
423 * 0 on the first line, which can trigger an arbitrary amount of code,
424 * possibly including finalizers (like __del__ methods or weakref callbacks)
425 * coded in Python, which in turn can release the GIL and allow other threads
426 * to run, etc. Such code may even invoke methods of `self` again, or cause
427 * cyclic gc to trigger, but-- oops! --self->containee still points to the
428 * object being torn down, and it may be in an insane state while being torn
429 * down. This has in fact been a rich historic source of miserable (rare &
430 * hard-to-diagnose) segfaulting (and other) bugs.
431 *
432 * The safe way is:
433 *
434 * Py_CLEAR(op);
435 *
436 * That arranges to set `op` to NULL _before_ decref'ing, so that any code
437 * triggered as a side-effect of `op` getting torn down no longer believes
438 * `op` points to a valid object.
439 *
440 * There are cases where it's safe to use the naive code, but they're brittle.
441 * For example, if `op` points to a Python integer, you know that destroying
442 * one of those can't cause problems -- but in part that relies on that
443 * Python integers aren't currently weakly referencable. Best practice is
444 * to use Py_CLEAR() even if you can't think of a reason for why you need to.
445 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000446#define Py_CLEAR(op) \
447 do { \
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100448 PyObject *_py_tmp = _PyObject_CAST(op); \
Benjamin Petersonda5eb5a2013-05-27 14:46:14 -0700449 if (_py_tmp != NULL) { \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000450 (op) = NULL; \
451 Py_DECREF(_py_tmp); \
452 } \
453 } while (0)
Jim Fulton8c5aeaa2004-07-14 19:07:35 +0000454
Victor Stinner541497e2018-10-29 20:52:41 +0100455/* Function to use in case the object pointer can be NULL: */
456static inline void _Py_XINCREF(PyObject *op)
457{
458 if (op != NULL) {
459 Py_INCREF(op);
460 }
461}
Benjamin Petersonda5eb5a2013-05-27 14:46:14 -0700462
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100463#define Py_XINCREF(op) _Py_XINCREF(_PyObject_CAST(op))
Victor Stinner541497e2018-10-29 20:52:41 +0100464
465static inline void _Py_XDECREF(PyObject *op)
466{
467 if (op != NULL) {
468 Py_DECREF(op);
469 }
470}
471
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100472#define Py_XDECREF(op) _Py_XDECREF(_PyObject_CAST(op))
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000473
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000474/*
Thomas Heller1328b522004-04-22 17:23:49 +0000475These are provided as conveniences to Python runtime embedders, so that
476they can have object code that is not dependent on Python compilation flags.
477*/
478PyAPI_FUNC(void) Py_IncRef(PyObject *);
479PyAPI_FUNC(void) Py_DecRef(PyObject *);
480
481/*
Guido van Rossumcaa63801995-01-12 11:45:45 +0000482_Py_NoneStruct is an object of undefined type which can be used in contexts
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000483where NULL (nil) is not suitable (since NULL often means 'error').
484
Guido van Rossumcaa63801995-01-12 11:45:45 +0000485Don't forget to apply Py_INCREF() when returning this value!!!
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000486*/
Mark Hammonda2905272002-07-29 13:42:14 +0000487PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
Guido van Rossumcaa63801995-01-12 11:45:45 +0000488#define Py_None (&_Py_NoneStruct)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000489
Brett Cannond05235e2003-10-19 21:19:40 +0000490/* Macro for returning Py_None from a function */
Tim Peters5980ff22004-07-22 01:46:43 +0000491#define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None
Brett Cannond05235e2003-10-19 21:19:40 +0000492
Neil Schemenauera7ed6942001-01-04 01:31:50 +0000493/*
494Py_NotImplemented is a singleton used to signal that an operation is
495not implemented for a given type combination.
496*/
Mark Hammonda2905272002-07-29 13:42:14 +0000497PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
Neil Schemenauera7ed6942001-01-04 01:31:50 +0000498#define Py_NotImplemented (&_Py_NotImplementedStruct)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000499
Brian Curtin7d2f9e12011-08-10 20:05:21 -0500500/* Macro for returning Py_NotImplemented from a function */
501#define Py_RETURN_NOTIMPLEMENTED \
502 return Py_INCREF(Py_NotImplemented), Py_NotImplemented
503
Guido van Rossum5f284ce2001-01-17 15:20:39 +0000504/* Rich comparison opcodes */
505#define Py_LT 0
506#define Py_LE 1
507#define Py_EQ 2
508#define Py_NE 3
509#define Py_GT 4
510#define Py_GE 5
511
stratakise8b19652017-11-02 11:32:54 +0100512/*
513 * Macro for implementing rich comparisons
514 *
515 * Needs to be a macro because any C-comparable type can be used.
516 */
517#define Py_RETURN_RICHCOMPARE(val1, val2, op) \
518 do { \
519 switch (op) { \
520 case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
521 case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
522 case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
523 case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
524 case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
525 case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
526 default: \
527 Py_UNREACHABLE(); \
528 } \
529 } while (0)
530
Guido van Rossumb6775db1994-08-01 11:34:53 +0000531
532/*
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000533More conventions
534================
535
536Argument Checking
537-----------------
538
539Functions that take objects as arguments normally don't check for nil
540arguments, but they do check the type of the argument, and return an
541error if the function doesn't apply to the type.
542
543Failure Modes
544-------------
545
546Functions may fail for a variety of reasons, including running out of
Guido van Rossum3f5da241990-12-20 15:06:42 +0000547memory. This is communicated to the caller in two ways: an error string
548is set (see errors.h), and the function result differs: functions that
549normally return a pointer return NULL for failure, functions returning
550an integer return -1 (which could be a legal return value too!), and
551other functions return 0 for success and -1 for failure.
Tim Peters4be93d02002-07-07 19:59:50 +0000552Callers should always check for errors before using the result. If
553an error was set, the caller must either explicitly clear it, or pass
554the error on to its caller.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000555
556Reference Counts
557----------------
558
559It takes a while to get used to the proper usage of reference counts.
560
561Functions that create an object set the reference count to 1; such new
Guido van Rossumcaa63801995-01-12 11:45:45 +0000562objects must be stored somewhere or destroyed again with Py_DECREF().
Alex Martelli721b7762003-11-09 16:38:39 +0000563Some functions that 'store' objects, such as PyTuple_SetItem() and
564PyList_SetItem(),
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000565don't increment the reference count of the object, since the most
566frequent use is to store a fresh object. Functions that 'retrieve'
Alex Martelli721b7762003-11-09 16:38:39 +0000567objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
Guido van Rossumcaa63801995-01-12 11:45:45 +0000568don't increment
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000569the reference count, since most frequently the object is only looked at
570quickly. Thus, to retrieve an object and store it again, the caller
Guido van Rossumcaa63801995-01-12 11:45:45 +0000571must call Py_INCREF() explicitly.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000572
Alex Martelli721b7762003-11-09 16:38:39 +0000573NOTE: functions that 'consume' a reference count, like
574PyList_SetItem(), consume the reference even if the object wasn't
575successfully stored, to simplify error handling.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000576
577It seems attractive to make other functions that take an object as
Alex Martelli721b7762003-11-09 16:38:39 +0000578argument consume a reference count; however, this may quickly get
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000579confusing (even the current practice is already confusing). Consider
Guido van Rossumcaa63801995-01-12 11:45:45 +0000580it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000581times.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000582*/
Guido van Rossuma3309961993-07-28 09:05:47 +0000583
Victor Stinner626bff82018-10-25 17:31:10 +0200584#ifndef Py_LIMITED_API
Victor Stinner6eb99662018-11-26 17:09:16 +0100585# define Py_CPYTHON_OBJECT_H
586# include "cpython/object.h"
587# undef Py_CPYTHON_OBJECT_H
Victor Stinner626bff82018-10-25 17:31:10 +0200588#endif
589
Victor Stinner509dd902020-02-05 14:24:17 +0100590
591static inline int
592PyType_HasFeature(PyTypeObject *type, unsigned long feature) {
593#ifdef Py_LIMITED_API
594 return ((PyType_GetFlags(type) & feature) != 0);
595#else
596 return ((type->tp_flags & feature) != 0);
597#endif
598}
599
600#define PyType_FastSubclass(type, flag) PyType_HasFeature(type, flag)
601
602static inline int _PyType_Check(PyObject *op) {
603 return PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS);
604}
605#define PyType_Check(op) _PyType_Check(_PyObject_CAST(op))
606
607static inline int _PyType_CheckExact(PyObject *op) {
608 return (Py_TYPE(op) == &PyType_Type);
609}
610#define PyType_CheckExact(op) _PyType_CheckExact(_PyObject_CAST(op))
611
Guido van Rossuma3309961993-07-28 09:05:47 +0000612#ifdef __cplusplus
613}
614#endif
615#endif /* !Py_OBJECT_H */