blob: 38794a0e98cea881f38aa729fab57da80fd4afd8 [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
Petr Viktorin3f563ce2020-02-06 15:48:27 +0100282#define Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11)
283// Backwards compatibility alias for API that was provisional in Python 3.8
284#define _Py_TPFLAGS_HAVE_VECTORCALL Py_TPFLAGS_HAVE_VECTORCALL
Jeroen Demeyeraacc77f2019-05-29 20:31:52 +0200285#endif
286
Guido van Rossum9b9c9722001-08-10 17:37:02 +0000287/* Set if the type is 'ready' -- fully initialized */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100288#define Py_TPFLAGS_READY (1UL << 12)
Guido van Rossum9b9c9722001-08-10 17:37:02 +0000289
290/* Set while the type is being 'readied', to prevent recursive ready calls */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100291#define Py_TPFLAGS_READYING (1UL << 13)
Guido van Rossum9b9c9722001-08-10 17:37:02 +0000292
Antoine Pitrouada319b2019-05-29 22:12:38 +0200293/* Objects support garbage collection (see objimpl.h) */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100294#define Py_TPFLAGS_HAVE_GC (1UL << 14)
Neil Schemenauer31ec1422001-08-29 23:46:35 +0000295
Guido van Rossum38fff8c2006-03-07 18:50:55 +0000296/* These two bits are preserved for Stackless Python, next after this is 17 */
Christian Tismer6695ba82003-05-20 15:14:31 +0000297#ifdef STACKLESS
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100298#define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15)
Christian Tismer6695ba82003-05-20 15:14:31 +0000299#else
Christian Tismerc26ff412003-05-23 03:33:35 +0000300#define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
Christian Tismer6695ba82003-05-20 15:14:31 +0000301#endif
302
Jeroen Demeyereb65e242019-05-28 14:42:53 +0200303/* Objects behave like an unbound method */
304#define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17)
305
Christian Heimesa62da1d2008-01-12 19:39:10 +0000306/* Objects support type attribute cache */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100307#define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18)
308#define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19)
Christian Heimesa62da1d2008-01-12 19:39:10 +0000309
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000310/* Type is abstract and cannot be instantiated */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100311#define Py_TPFLAGS_IS_ABSTRACT (1UL << 20)
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000312
Thomas Wouters27d517b2007-02-25 20:39:11 +0000313/* These flags are used to determine if a type is a subclass. */
Victor Stinner4ca1cf32012-10-30 23:40:45 +0100314#define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24)
315#define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25)
316#define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26)
317#define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27)
318#define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28)
319#define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29)
320#define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30)
321#define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31)
Thomas Wouters27d517b2007-02-25 20:39:11 +0000322
Guido van Rossumbacca542001-01-24 22:13:48 +0000323#define Py_TPFLAGS_DEFAULT ( \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000324 Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
325 Py_TPFLAGS_HAVE_VERSION_TAG | \
326 0)
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000327
Antoine Pitrou796564c2013-07-30 19:59:21 +0200328/* NOTE: The following flags reuse lower bits (removed as part of the
329 * Python 3.0 transition). */
330
Hansraj Das10e5c662019-07-06 03:07:15 +0530331/* The following flag is kept for compatibility. Starting with 3.8,
332 * binary compatibility of C extensions across feature releases of
Antoine Pitrouada319b2019-05-29 22:12:38 +0200333 * Python is not supported anymore, except when using the stable ABI.
334 */
335
Antoine Pitrou796564c2013-07-30 19:59:21 +0200336/* Type structure has tp_finalize member (3.4) */
337#define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0)
338
Guido van Rossum36eef3c1998-10-08 02:10:56 +0000339
340/*
Guido van Rossumcaa63801995-01-12 11:45:45 +0000341The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
Tim Peters4be93d02002-07-07 19:59:50 +0000342reference counts. Py_DECREF calls the object's deallocator function when
343the refcount falls to 0; for
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000344objects that don't contain references to other objects or heap memory
345this can be the standard function free(). Both macros can be used
Tim Peters4be93d02002-07-07 19:59:50 +0000346wherever a void expression is allowed. The argument must not be a
Benjamin Peterson2a691a82008-03-31 01:51:45 +0000347NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead.
Tim Peters4be93d02002-07-07 19:59:50 +0000348The macro _Py_NewReference(op) initialize reference counts to 1, and
349in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
350bookkeeping appropriate to the special build.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000351
352We assume that the reference count field can never overflow; this can
Tim Peters4be93d02002-07-07 19:59:50 +0000353be proven when the size of the field is the same as the pointer size, so
354we ignore the possibility. Provided a C int is at least 32 bits (which
355is implicitly assumed in many parts of this code), that's enough for
356about 2**31 references to an object.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000357
Tim Peters4be93d02002-07-07 19:59:50 +0000358XXX The following became out of date in Python 2.2, but I'm not sure
359XXX what the full truth is now. Certainly, heap-allocated type objects
360XXX can and should be deallocated.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000361Type objects should never be deallocated; the type pointer in an object
362is not considered to be a reference to the type object, to save
363complications in the deallocation function. (This is actually a
364decision that's up to the implementer of each new type so if you want,
365you can count such references to the type object.)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000366*/
367
Tim Peters4be93d02002-07-07 19:59:50 +0000368#ifdef Py_REF_DEBUG
Neal Norwitz4281cef2006-03-04 19:58:13 +0000369PyAPI_DATA(Py_ssize_t) _Py_RefTotal;
Victor Stinner18618e652018-10-25 17:28:11 +0200370PyAPI_FUNC(void) _Py_NegativeRefcount(const char *filename, int lineno,
371 PyObject *op);
Tim Peters57f4ddd2002-07-10 06:34:15 +0000372#endif /* Py_REF_DEBUG */
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000373
Victor Stinner3c09dca2018-10-30 14:48:26 +0100374PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
375
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100376static inline void _Py_INCREF(PyObject *op)
377{
Victor Stinner49932fe2020-02-03 17:55:05 +0100378#ifdef Py_REF_DEBUG
379 _Py_RefTotal++;
380#endif
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100381 op->ob_refcnt++;
382}
383
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100384#define Py_INCREF(op) _Py_INCREF(_PyObject_CAST(op))
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100385
Victor Stinnerf3a0a6b2020-01-08 21:03:45 +0100386static inline void _Py_DECREF(
387#ifdef Py_REF_DEBUG
388 const char *filename, int lineno,
389#endif
390 PyObject *op)
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100391{
Victor Stinner49932fe2020-02-03 17:55:05 +0100392#ifdef Py_REF_DEBUG
393 _Py_RefTotal--;
394#endif
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100395 if (--op->ob_refcnt != 0) {
396#ifdef Py_REF_DEBUG
397 if (op->ob_refcnt < 0) {
398 _Py_NegativeRefcount(filename, lineno, op);
399 }
400#endif
401 }
402 else {
403 _Py_Dealloc(op);
404 }
405}
406
Victor Stinnerf3a0a6b2020-01-08 21:03:45 +0100407#ifdef Py_REF_DEBUG
408# define Py_DECREF(op) _Py_DECREF(__FILE__, __LINE__, _PyObject_CAST(op))
409#else
410# define Py_DECREF(op) _Py_DECREF(_PyObject_CAST(op))
411#endif
Victor Stinner2aaf0c12018-10-29 13:43:07 +0100412
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000413
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000414/* Safely decref `op` and set `op` to NULL, especially useful in tp_clear
Berker Peksag4882cac2015-04-14 09:30:01 +0300415 * and tp_dealloc implementations.
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000416 *
417 * Note that "the obvious" code can be deadly:
418 *
419 * Py_XDECREF(op);
420 * op = NULL;
421 *
422 * Typically, `op` is something like self->containee, and `self` is done
423 * using its `containee` member. In the code sequence above, suppose
424 * `containee` is non-NULL with a refcount of 1. Its refcount falls to
425 * 0 on the first line, which can trigger an arbitrary amount of code,
426 * possibly including finalizers (like __del__ methods or weakref callbacks)
427 * coded in Python, which in turn can release the GIL and allow other threads
428 * to run, etc. Such code may even invoke methods of `self` again, or cause
429 * cyclic gc to trigger, but-- oops! --self->containee still points to the
430 * object being torn down, and it may be in an insane state while being torn
431 * down. This has in fact been a rich historic source of miserable (rare &
432 * hard-to-diagnose) segfaulting (and other) bugs.
433 *
434 * The safe way is:
435 *
436 * Py_CLEAR(op);
437 *
438 * That arranges to set `op` to NULL _before_ decref'ing, so that any code
439 * triggered as a side-effect of `op` getting torn down no longer believes
440 * `op` points to a valid object.
441 *
442 * There are cases where it's safe to use the naive code, but they're brittle.
443 * For example, if `op` points to a Python integer, you know that destroying
444 * one of those can't cause problems -- but in part that relies on that
445 * Python integers aren't currently weakly referencable. Best practice is
446 * to use Py_CLEAR() even if you can't think of a reason for why you need to.
447 */
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000448#define Py_CLEAR(op) \
449 do { \
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100450 PyObject *_py_tmp = _PyObject_CAST(op); \
Benjamin Petersonda5eb5a2013-05-27 14:46:14 -0700451 if (_py_tmp != NULL) { \
Antoine Pitrouf95a1b32010-05-09 15:52:27 +0000452 (op) = NULL; \
453 Py_DECREF(_py_tmp); \
454 } \
455 } while (0)
Jim Fulton8c5aeaa2004-07-14 19:07:35 +0000456
Victor Stinner541497e2018-10-29 20:52:41 +0100457/* Function to use in case the object pointer can be NULL: */
458static inline void _Py_XINCREF(PyObject *op)
459{
460 if (op != NULL) {
461 Py_INCREF(op);
462 }
463}
Benjamin Petersonda5eb5a2013-05-27 14:46:14 -0700464
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100465#define Py_XINCREF(op) _Py_XINCREF(_PyObject_CAST(op))
Victor Stinner541497e2018-10-29 20:52:41 +0100466
467static inline void _Py_XDECREF(PyObject *op)
468{
469 if (op != NULL) {
470 Py_DECREF(op);
471 }
472}
473
Victor Stinner2ff8fb72018-11-22 02:57:29 +0100474#define Py_XDECREF(op) _Py_XDECREF(_PyObject_CAST(op))
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000475
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000476/*
Thomas Heller1328b522004-04-22 17:23:49 +0000477These are provided as conveniences to Python runtime embedders, so that
478they can have object code that is not dependent on Python compilation flags.
479*/
480PyAPI_FUNC(void) Py_IncRef(PyObject *);
481PyAPI_FUNC(void) Py_DecRef(PyObject *);
482
483/*
Guido van Rossumcaa63801995-01-12 11:45:45 +0000484_Py_NoneStruct is an object of undefined type which can be used in contexts
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000485where NULL (nil) is not suitable (since NULL often means 'error').
486
Guido van Rossumcaa63801995-01-12 11:45:45 +0000487Don't forget to apply Py_INCREF() when returning this value!!!
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000488*/
Mark Hammonda2905272002-07-29 13:42:14 +0000489PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
Guido van Rossumcaa63801995-01-12 11:45:45 +0000490#define Py_None (&_Py_NoneStruct)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000491
Brett Cannond05235e2003-10-19 21:19:40 +0000492/* Macro for returning Py_None from a function */
Tim Peters5980ff22004-07-22 01:46:43 +0000493#define Py_RETURN_NONE return Py_INCREF(Py_None), Py_None
Brett Cannond05235e2003-10-19 21:19:40 +0000494
Neil Schemenauera7ed6942001-01-04 01:31:50 +0000495/*
496Py_NotImplemented is a singleton used to signal that an operation is
497not implemented for a given type combination.
498*/
Mark Hammonda2905272002-07-29 13:42:14 +0000499PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
Neil Schemenauera7ed6942001-01-04 01:31:50 +0000500#define Py_NotImplemented (&_Py_NotImplementedStruct)
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000501
Brian Curtin7d2f9e12011-08-10 20:05:21 -0500502/* Macro for returning Py_NotImplemented from a function */
503#define Py_RETURN_NOTIMPLEMENTED \
504 return Py_INCREF(Py_NotImplemented), Py_NotImplemented
505
Guido van Rossum5f284ce2001-01-17 15:20:39 +0000506/* Rich comparison opcodes */
507#define Py_LT 0
508#define Py_LE 1
509#define Py_EQ 2
510#define Py_NE 3
511#define Py_GT 4
512#define Py_GE 5
513
stratakise8b19652017-11-02 11:32:54 +0100514/*
515 * Macro for implementing rich comparisons
516 *
517 * Needs to be a macro because any C-comparable type can be used.
518 */
519#define Py_RETURN_RICHCOMPARE(val1, val2, op) \
520 do { \
521 switch (op) { \
522 case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
523 case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
524 case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
525 case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
526 case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
527 case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
528 default: \
529 Py_UNREACHABLE(); \
530 } \
531 } while (0)
532
Guido van Rossumb6775db1994-08-01 11:34:53 +0000533
534/*
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000535More conventions
536================
537
538Argument Checking
539-----------------
540
541Functions that take objects as arguments normally don't check for nil
542arguments, but they do check the type of the argument, and return an
543error if the function doesn't apply to the type.
544
545Failure Modes
546-------------
547
548Functions may fail for a variety of reasons, including running out of
Guido van Rossum3f5da241990-12-20 15:06:42 +0000549memory. This is communicated to the caller in two ways: an error string
550is set (see errors.h), and the function result differs: functions that
551normally return a pointer return NULL for failure, functions returning
552an integer return -1 (which could be a legal return value too!), and
553other functions return 0 for success and -1 for failure.
Tim Peters4be93d02002-07-07 19:59:50 +0000554Callers should always check for errors before using the result. If
555an error was set, the caller must either explicitly clear it, or pass
556the error on to its caller.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000557
558Reference Counts
559----------------
560
561It takes a while to get used to the proper usage of reference counts.
562
563Functions that create an object set the reference count to 1; such new
Guido van Rossumcaa63801995-01-12 11:45:45 +0000564objects must be stored somewhere or destroyed again with Py_DECREF().
Alex Martelli721b7762003-11-09 16:38:39 +0000565Some functions that 'store' objects, such as PyTuple_SetItem() and
566PyList_SetItem(),
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000567don't increment the reference count of the object, since the most
568frequent use is to store a fresh object. Functions that 'retrieve'
Alex Martelli721b7762003-11-09 16:38:39 +0000569objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
Guido van Rossumcaa63801995-01-12 11:45:45 +0000570don't increment
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000571the reference count, since most frequently the object is only looked at
572quickly. Thus, to retrieve an object and store it again, the caller
Guido van Rossumcaa63801995-01-12 11:45:45 +0000573must call Py_INCREF() explicitly.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000574
Alex Martelli721b7762003-11-09 16:38:39 +0000575NOTE: functions that 'consume' a reference count, like
576PyList_SetItem(), consume the reference even if the object wasn't
577successfully stored, to simplify error handling.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000578
579It seems attractive to make other functions that take an object as
Alex Martelli721b7762003-11-09 16:38:39 +0000580argument consume a reference count; however, this may quickly get
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000581confusing (even the current practice is already confusing). Consider
Guido van Rossumcaa63801995-01-12 11:45:45 +0000582it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000583times.
Guido van Rossum85a5fbb1990-10-14 12:07:46 +0000584*/
Guido van Rossuma3309961993-07-28 09:05:47 +0000585
Victor Stinner626bff82018-10-25 17:31:10 +0200586#ifndef Py_LIMITED_API
Victor Stinner6eb99662018-11-26 17:09:16 +0100587# define Py_CPYTHON_OBJECT_H
588# include "cpython/object.h"
589# undef Py_CPYTHON_OBJECT_H
Victor Stinner626bff82018-10-25 17:31:10 +0200590#endif
591
Victor Stinner509dd902020-02-05 14:24:17 +0100592
593static inline int
594PyType_HasFeature(PyTypeObject *type, unsigned long feature) {
595#ifdef Py_LIMITED_API
596 return ((PyType_GetFlags(type) & feature) != 0);
597#else
598 return ((type->tp_flags & feature) != 0);
599#endif
600}
601
602#define PyType_FastSubclass(type, flag) PyType_HasFeature(type, flag)
603
604static inline int _PyType_Check(PyObject *op) {
605 return PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS);
606}
607#define PyType_Check(op) _PyType_Check(_PyObject_CAST(op))
608
609static inline int _PyType_CheckExact(PyObject *op) {
610 return (Py_TYPE(op) == &PyType_Type);
611}
612#define PyType_CheckExact(op) _PyType_CheckExact(_PyObject_CAST(op))
613
Guido van Rossuma3309961993-07-28 09:05:47 +0000614#ifdef __cplusplus
615}
616#endif
617#endif /* !Py_OBJECT_H */