Branch data Line data Source code
1 : : #ifndef Py_OBJECT_H
2 : : #define Py_OBJECT_H
3 : : #ifdef __cplusplus
4 : : extern "C" {
5 : : #endif
6 : :
7 : :
8 : : /* Object and type object interface */
9 : :
10 : : /*
11 : : Objects are structures allocated on the heap. Special rules apply to
12 : : the use of objects to ensure they are properly garbage-collected.
13 : : Objects are never allocated statically or on the stack; they must be
14 : : accessed through special macros and functions only. (Type objects are
15 : : exceptions to the first rule; the standard types are represented by
16 : : statically initialized type objects, although work on type/class unification
17 : : for Python 2.2 made it possible to have heap-allocated type objects too).
18 : :
19 : : An object has a 'reference count' that is increased or decreased when a
20 : : pointer to the object is copied or deleted; when the reference count
21 : : reaches zero there are no references to the object left and it can be
22 : : removed from the heap.
23 : :
24 : : An object has a 'type' that determines what it represents and what kind
25 : : of data it contains. An object's type is fixed when it is created.
26 : : Types themselves are represented as objects; an object contains a
27 : : pointer to the corresponding type object. The type itself has a type
28 : : pointer pointing to the object representing the type 'type', which
29 : : contains a pointer to itself!.
30 : :
31 : : Objects do not float around in memory; once allocated an object keeps
32 : : the same size and address. Objects that must hold variable-size data
33 : : can contain pointers to variable-size parts of the object. Not all
34 : : objects of the same type have the same size; but the size cannot change
35 : : after allocation. (These restrictions are made so a reference to an
36 : : object can be simply a pointer -- moving an object would require
37 : : updating all the pointers, and changing an object's size would require
38 : : moving it if there was another object right next to it.)
39 : :
40 : : Objects are always accessed through pointers of the type 'PyObject *'.
41 : : The type 'PyObject' is a structure that only contains the reference count
42 : : and the type pointer. The actual memory allocated for an object
43 : : contains other data that can only be accessed after casting the pointer
44 : : to a pointer to a longer structure type. This longer type must start
45 : : with the reference count and type fields; the macro PyObject_HEAD should be
46 : : used for this (to accommodate for future changes). The implementation
47 : : of a particular object type can cast the object pointer to the proper
48 : : type and back.
49 : :
50 : : A standard interface exists for objects that contain an array of items
51 : : whose size is determined when the object is allocated.
52 : : */
53 : :
54 : : #include "pystats.h"
55 : :
56 : : /* Py_DEBUG implies Py_REF_DEBUG. */
57 : : #if defined(Py_DEBUG) && !defined(Py_REF_DEBUG)
58 : : # define Py_REF_DEBUG
59 : : #endif
60 : :
61 : : #if defined(Py_LIMITED_API) && defined(Py_TRACE_REFS)
62 : : # error Py_LIMITED_API is incompatible with Py_TRACE_REFS
63 : : #endif
64 : :
65 : : #ifdef Py_TRACE_REFS
66 : : /* Define pointers to support a doubly-linked list of all live heap objects. */
67 : : #define _PyObject_HEAD_EXTRA \
68 : : PyObject *_ob_next; \
69 : : PyObject *_ob_prev;
70 : :
71 : : #define _PyObject_EXTRA_INIT _Py_NULL, _Py_NULL,
72 : :
73 : : #else
74 : : # define _PyObject_HEAD_EXTRA
75 : : # define _PyObject_EXTRA_INIT
76 : : #endif
77 : :
78 : : /* PyObject_HEAD defines the initial segment of every PyObject. */
79 : : #define PyObject_HEAD PyObject ob_base;
80 : :
81 : : #define PyObject_HEAD_INIT(type) \
82 : : { _PyObject_EXTRA_INIT \
83 : : 1, (type) },
84 : :
85 : : #define PyVarObject_HEAD_INIT(type, size) \
86 : : { PyObject_HEAD_INIT(type) (size) },
87 : :
88 : : /* PyObject_VAR_HEAD defines the initial segment of all variable-size
89 : : * container objects. These end with a declaration of an array with 1
90 : : * element, but enough space is malloc'ed so that the array actually
91 : : * has room for ob_size elements. Note that ob_size is an element count,
92 : : * not necessarily a byte count.
93 : : */
94 : : #define PyObject_VAR_HEAD PyVarObject ob_base;
95 : : #define Py_INVALID_SIZE (Py_ssize_t)-1
96 : :
97 : : /* Nothing is actually declared to be a PyObject, but every pointer to
98 : : * a Python object can be cast to a PyObject*. This is inheritance built
99 : : * by hand. Similarly every pointer to a variable-size Python object can,
100 : : * in addition, be cast to PyVarObject*.
101 : : */
102 : : struct _object {
103 : : _PyObject_HEAD_EXTRA
104 : : Py_ssize_t ob_refcnt;
105 : : PyTypeObject *ob_type;
106 : : };
107 : :
108 : : /* Cast argument to PyObject* type. */
109 : : #define _PyObject_CAST(op) _Py_CAST(PyObject*, (op))
110 : :
111 : : typedef struct {
112 : : PyObject ob_base;
113 : : Py_ssize_t ob_size; /* Number of items in variable part */
114 : : } PyVarObject;
115 : :
116 : : /* Cast argument to PyVarObject* type. */
117 : : #define _PyVarObject_CAST(op) _Py_CAST(PyVarObject*, (op))
118 : :
119 : :
120 : : // Test if the 'x' object is the 'y' object, the same as "x is y" in Python.
121 : : PyAPI_FUNC(int) Py_Is(PyObject *x, PyObject *y);
122 : : #define Py_Is(x, y) ((x) == (y))
123 : :
124 : :
125 : 8040154 : static inline Py_ssize_t Py_REFCNT(PyObject *ob) {
126 : 8040154 : return ob->ob_refcnt;
127 : : }
128 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
129 : : # define Py_REFCNT(ob) Py_REFCNT(_PyObject_CAST(ob))
130 : : #endif
131 : :
132 : :
133 : : // bpo-39573: The Py_SET_TYPE() function must be used to set an object type.
134 : 328836979 : static inline PyTypeObject* Py_TYPE(PyObject *ob) {
135 : 328836979 : return ob->ob_type;
136 : : }
137 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
138 : : # define Py_TYPE(ob) Py_TYPE(_PyObject_CAST(ob))
139 : : #endif
140 : :
141 : : // bpo-39573: The Py_SET_SIZE() function must be used to set an object size.
142 : 112896026 : static inline Py_ssize_t Py_SIZE(PyObject *ob) {
143 : 112896026 : PyVarObject *var_ob = _PyVarObject_CAST(ob);
144 : 112896026 : return var_ob->ob_size;
145 : : }
146 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
147 : : # define Py_SIZE(ob) Py_SIZE(_PyObject_CAST(ob))
148 : : #endif
149 : :
150 : :
151 : 67649253 : static inline int Py_IS_TYPE(PyObject *ob, PyTypeObject *type) {
152 : 67649253 : return Py_TYPE(ob) == type;
153 : : }
154 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
155 : : # define Py_IS_TYPE(ob, type) Py_IS_TYPE(_PyObject_CAST(ob), (type))
156 : : #endif
157 : :
158 : :
159 : 31466638 : static inline void Py_SET_REFCNT(PyObject *ob, Py_ssize_t refcnt) {
160 : 31466638 : ob->ob_refcnt = refcnt;
161 : 31466638 : }
162 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
163 : : # define Py_SET_REFCNT(ob, refcnt) Py_SET_REFCNT(_PyObject_CAST(ob), (refcnt))
164 : : #endif
165 : :
166 : :
167 : 28346564 : static inline void Py_SET_TYPE(PyObject *ob, PyTypeObject *type) {
168 : 28346564 : ob->ob_type = type;
169 : 28346564 : }
170 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
171 : : # define Py_SET_TYPE(ob, type) Py_SET_TYPE(_PyObject_CAST(ob), type)
172 : : #endif
173 : :
174 : :
175 : 16923540 : static inline void Py_SET_SIZE(PyVarObject *ob, Py_ssize_t size) {
176 : 16923540 : ob->ob_size = size;
177 : 16923540 : }
178 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
179 : : # define Py_SET_SIZE(ob, size) Py_SET_SIZE(_PyVarObject_CAST(ob), (size))
180 : : #endif
181 : :
182 : :
183 : : /*
184 : : Type objects contain a string containing the type name (to help somewhat
185 : : in debugging), the allocation parameters (see PyObject_New() and
186 : : PyObject_NewVar()),
187 : : and methods for accessing objects of the type. Methods are optional, a
188 : : nil pointer meaning that particular kind of access is not available for
189 : : this type. The Py_DECREF() macro uses the tp_dealloc method without
190 : : checking for a nil pointer; it should always be implemented except if
191 : : the implementation can guarantee that the reference count will never
192 : : reach zero (e.g., for statically allocated type objects).
193 : :
194 : : NB: the methods for certain type groups are now contained in separate
195 : : method blocks.
196 : : */
197 : :
198 : : typedef PyObject * (*unaryfunc)(PyObject *);
199 : : typedef PyObject * (*binaryfunc)(PyObject *, PyObject *);
200 : : typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *);
201 : : typedef int (*inquiry)(PyObject *);
202 : : typedef Py_ssize_t (*lenfunc)(PyObject *);
203 : : typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t);
204 : : typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t);
205 : : typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *);
206 : : typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *);
207 : : typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *);
208 : :
209 : : typedef int (*objobjproc)(PyObject *, PyObject *);
210 : : typedef int (*visitproc)(PyObject *, void *);
211 : : typedef int (*traverseproc)(PyObject *, visitproc, void *);
212 : :
213 : :
214 : : typedef void (*freefunc)(void *);
215 : : typedef void (*destructor)(PyObject *);
216 : : typedef PyObject *(*getattrfunc)(PyObject *, char *);
217 : : typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
218 : : typedef int (*setattrfunc)(PyObject *, char *, PyObject *);
219 : : typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *);
220 : : typedef PyObject *(*reprfunc)(PyObject *);
221 : : typedef Py_hash_t (*hashfunc)(PyObject *);
222 : : typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int);
223 : : typedef PyObject *(*getiterfunc) (PyObject *);
224 : : typedef PyObject *(*iternextfunc) (PyObject *);
225 : : typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *);
226 : : typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *);
227 : : typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
228 : : typedef PyObject *(*newfunc)(PyTypeObject *, PyObject *, PyObject *);
229 : : typedef PyObject *(*allocfunc)(PyTypeObject *, Py_ssize_t);
230 : :
231 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030c0000 // 3.12
232 : : typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args,
233 : : size_t nargsf, PyObject *kwnames);
234 : : #endif
235 : :
236 : : typedef struct{
237 : : int slot; /* slot id, see below */
238 : : void *pfunc; /* function pointer */
239 : : } PyType_Slot;
240 : :
241 : : typedef struct{
242 : : const char* name;
243 : : int basicsize;
244 : : int itemsize;
245 : : unsigned int flags;
246 : : PyType_Slot *slots; /* terminated by slot==0. */
247 : : } PyType_Spec;
248 : :
249 : : PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*);
250 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
251 : : PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*);
252 : : #endif
253 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000
254 : : PyAPI_FUNC(void*) PyType_GetSlot(PyTypeObject*, int);
255 : : #endif
256 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000
257 : : PyAPI_FUNC(PyObject*) PyType_FromModuleAndSpec(PyObject *, PyType_Spec *, PyObject *);
258 : : PyAPI_FUNC(PyObject *) PyType_GetModule(PyTypeObject *);
259 : : PyAPI_FUNC(void *) PyType_GetModuleState(PyTypeObject *);
260 : : #endif
261 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030B0000
262 : : PyAPI_FUNC(PyObject *) PyType_GetName(PyTypeObject *);
263 : : PyAPI_FUNC(PyObject *) PyType_GetQualName(PyTypeObject *);
264 : : #endif
265 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
266 : : PyAPI_FUNC(PyObject *) PyType_FromMetaclass(PyTypeObject*, PyObject*, PyType_Spec*, PyObject*);
267 : : #endif
268 : :
269 : : /* Generic type check */
270 : : PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *);
271 : :
272 : 7876598 : static inline int PyObject_TypeCheck(PyObject *ob, PyTypeObject *type) {
273 [ + + + + ]: 7876598 : return Py_IS_TYPE(ob, type) || PyType_IsSubtype(Py_TYPE(ob), type);
274 : : }
275 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
276 : : # define PyObject_TypeCheck(ob, type) PyObject_TypeCheck(_PyObject_CAST(ob), (type))
277 : : #endif
278 : :
279 : : PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */
280 : : PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */
281 : : PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */
282 : :
283 : : PyAPI_FUNC(unsigned long) PyType_GetFlags(PyTypeObject*);
284 : :
285 : : PyAPI_FUNC(int) PyType_Ready(PyTypeObject *);
286 : : PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t);
287 : : PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *,
288 : : PyObject *, PyObject *);
289 : : PyAPI_FUNC(unsigned int) PyType_ClearCache(void);
290 : : PyAPI_FUNC(void) PyType_Modified(PyTypeObject *);
291 : :
292 : : /* Generic operations on objects */
293 : : PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
294 : : PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
295 : : PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *);
296 : : PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *);
297 : : PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
298 : : PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
299 : : PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *);
300 : : PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *);
301 : : PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *);
302 : : PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
303 : : PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
304 : : PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
305 : : PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *);
306 : : PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
307 : : PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, PyObject *, PyObject *);
308 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
309 : : PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *);
310 : : #endif
311 : : PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *);
312 : : PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *);
313 : : PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
314 : : PyAPI_FUNC(int) PyObject_Not(PyObject *);
315 : : PyAPI_FUNC(int) PyCallable_Check(PyObject *);
316 : : PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
317 : :
318 : : /* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a
319 : : list of strings. PyObject_Dir(NULL) is like builtins.dir(),
320 : : returning the names of the current locals. In this case, if there are
321 : : no current locals, NULL is returned, and PyErr_Occurred() is false.
322 : : */
323 : : PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
324 : :
325 : : /* Pickle support. */
326 : : #ifndef Py_LIMITED_API
327 : : PyAPI_FUNC(PyObject *) _PyObject_GetState(PyObject *);
328 : : #endif
329 : :
330 : :
331 : : /* Helpers for printing recursive container types */
332 : : PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
333 : : PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
334 : :
335 : : /* Flag bits for printing: */
336 : : #define Py_PRINT_RAW 1 /* No string quotes etc. */
337 : :
338 : : /*
339 : : Type flags (tp_flags)
340 : :
341 : : These flags are used to change expected features and behavior for a
342 : : particular type.
343 : :
344 : : Arbitration of the flag bit positions will need to be coordinated among
345 : : all extension writers who publicly release their extensions (this will
346 : : be fewer than you might expect!).
347 : :
348 : : Most flags were removed as of Python 3.0 to make room for new flags. (Some
349 : : flags are not for backwards compatibility but to indicate the presence of an
350 : : optional feature; these flags remain of course.)
351 : :
352 : : Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
353 : :
354 : : Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
355 : : given type object has a specified feature.
356 : : */
357 : :
358 : : #ifndef Py_LIMITED_API
359 : :
360 : : /* Track types initialized using _PyStaticType_InitBuiltin(). */
361 : : #define _Py_TPFLAGS_STATIC_BUILTIN (1 << 1)
362 : :
363 : : /* Placement of weakref pointers are managed by the VM, not by the type.
364 : : * The VM will automatically set tp_weaklistoffset.
365 : : */
366 : : #define Py_TPFLAGS_MANAGED_WEAKREF (1 << 3)
367 : :
368 : : /* Placement of dict (and values) pointers are managed by the VM, not by the type.
369 : : * The VM will automatically set tp_dictoffset.
370 : : */
371 : : #define Py_TPFLAGS_MANAGED_DICT (1 << 4)
372 : :
373 : : #define Py_TPFLAGS_PREHEADER (Py_TPFLAGS_MANAGED_WEAKREF | Py_TPFLAGS_MANAGED_DICT)
374 : :
375 : : /* Set if instances of the type object are treated as sequences for pattern matching */
376 : : #define Py_TPFLAGS_SEQUENCE (1 << 5)
377 : : /* Set if instances of the type object are treated as mappings for pattern matching */
378 : : #define Py_TPFLAGS_MAPPING (1 << 6)
379 : : #endif
380 : :
381 : : /* Disallow creating instances of the type: set tp_new to NULL and don't create
382 : : * the "__new__" key in the type dictionary. */
383 : : #define Py_TPFLAGS_DISALLOW_INSTANTIATION (1UL << 7)
384 : :
385 : : /* Set if the type object is immutable: type attributes cannot be set nor deleted */
386 : : #define Py_TPFLAGS_IMMUTABLETYPE (1UL << 8)
387 : :
388 : : /* Set if the type object is dynamically allocated */
389 : : #define Py_TPFLAGS_HEAPTYPE (1UL << 9)
390 : :
391 : : /* Set if the type allows subclassing */
392 : : #define Py_TPFLAGS_BASETYPE (1UL << 10)
393 : :
394 : : /* Set if the type implements the vectorcall protocol (PEP 590) */
395 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
396 : : #define Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11)
397 : : #ifndef Py_LIMITED_API
398 : : // Backwards compatibility alias for API that was provisional in Python 3.8
399 : : #define _Py_TPFLAGS_HAVE_VECTORCALL Py_TPFLAGS_HAVE_VECTORCALL
400 : : #endif
401 : : #endif
402 : :
403 : : /* Set if the type is 'ready' -- fully initialized */
404 : : #define Py_TPFLAGS_READY (1UL << 12)
405 : :
406 : : /* Set while the type is being 'readied', to prevent recursive ready calls */
407 : : #define Py_TPFLAGS_READYING (1UL << 13)
408 : :
409 : : /* Objects support garbage collection (see objimpl.h) */
410 : : #define Py_TPFLAGS_HAVE_GC (1UL << 14)
411 : :
412 : : /* These two bits are preserved for Stackless Python, next after this is 17 */
413 : : #ifdef STACKLESS
414 : : #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15)
415 : : #else
416 : : #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
417 : : #endif
418 : :
419 : : /* Objects behave like an unbound method */
420 : : #define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17)
421 : :
422 : : /* Object has up-to-date type attribute cache */
423 : : #define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19)
424 : :
425 : : /* Type is abstract and cannot be instantiated */
426 : : #define Py_TPFLAGS_IS_ABSTRACT (1UL << 20)
427 : :
428 : : // This undocumented flag gives certain built-ins their unique pattern-matching
429 : : // behavior, which allows a single positional subpattern to match against the
430 : : // subject itself (rather than a mapped attribute on it):
431 : : #define _Py_TPFLAGS_MATCH_SELF (1UL << 22)
432 : :
433 : : /* These flags are used to determine if a type is a subclass. */
434 : : #define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24)
435 : : #define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25)
436 : : #define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26)
437 : : #define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27)
438 : : #define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28)
439 : : #define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29)
440 : : #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30)
441 : : #define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31)
442 : :
443 : : #define Py_TPFLAGS_DEFAULT ( \
444 : : Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
445 : : 0)
446 : :
447 : : /* NOTE: Some of the following flags reuse lower bits (removed as part of the
448 : : * Python 3.0 transition). */
449 : :
450 : : /* The following flags are kept for compatibility; in previous
451 : : * versions they indicated presence of newer tp_* fields on the
452 : : * type struct.
453 : : * Starting with 3.8, binary compatibility of C extensions across
454 : : * feature releases of Python is not supported anymore (except when
455 : : * using the stable ABI, in which all classes are created dynamically,
456 : : * using the interpreter's memory layout.)
457 : : * Note that older extensions using the stable ABI set these flags,
458 : : * so the bits must not be repurposed.
459 : : */
460 : : #define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0)
461 : : #define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18)
462 : :
463 : :
464 : : /*
465 : : The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
466 : : reference counts. Py_DECREF calls the object's deallocator function when
467 : : the refcount falls to 0; for
468 : : objects that don't contain references to other objects or heap memory
469 : : this can be the standard function free(). Both macros can be used
470 : : wherever a void expression is allowed. The argument must not be a
471 : : NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead.
472 : : The macro _Py_NewReference(op) initialize reference counts to 1, and
473 : : in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
474 : : bookkeeping appropriate to the special build.
475 : :
476 : : We assume that the reference count field can never overflow; this can
477 : : be proven when the size of the field is the same as the pointer size, so
478 : : we ignore the possibility. Provided a C int is at least 32 bits (which
479 : : is implicitly assumed in many parts of this code), that's enough for
480 : : about 2**31 references to an object.
481 : :
482 : : XXX The following became out of date in Python 2.2, but I'm not sure
483 : : XXX what the full truth is now. Certainly, heap-allocated type objects
484 : : XXX can and should be deallocated.
485 : : Type objects should never be deallocated; the type pointer in an object
486 : : is not considered to be a reference to the type object, to save
487 : : complications in the deallocation function. (This is actually a
488 : : decision that's up to the implementer of each new type so if you want,
489 : : you can count such references to the type object.)
490 : : */
491 : :
492 : : #ifdef Py_REF_DEBUG
493 : : # if defined(Py_LIMITED_API) && Py_LIMITED_API+0 < 0x030A0000
494 : : extern Py_ssize_t _Py_RefTotal;
495 : : # define _Py_INC_REFTOTAL() _Py_RefTotal++
496 : : # define _Py_DEC_REFTOTAL() _Py_RefTotal--
497 : : # elif defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
498 : : extern void _Py_IncRefTotal(void);
499 : : extern void _Py_DecRefTotal(void);
500 : : # define _Py_INC_REFTOTAL() _Py_IncRefTotal()
501 : : # define _Py_DEC_REFTOTAL() _Py_DecRefTotal()
502 : : # elif !defined(Py_LIMITED_API) || Py_LIMITED_API+0 > 0x030C0000
503 : : extern void _Py_IncRefTotal_DO_NOT_USE_THIS(void);
504 : : extern void _Py_DecRefTotal_DO_NOT_USE_THIS(void);
505 : : # define _Py_INC_REFTOTAL() _Py_IncRefTotal_DO_NOT_USE_THIS()
506 : : # define _Py_DEC_REFTOTAL() _Py_DecRefTotal_DO_NOT_USE_THIS()
507 : : # endif
508 : : PyAPI_FUNC(void) _Py_NegativeRefcount(const char *filename, int lineno,
509 : : PyObject *op);
510 : : #endif /* Py_REF_DEBUG */
511 : :
512 : : PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
513 : :
514 : : /*
515 : : These are provided as conveniences to Python runtime embedders, so that
516 : : they can have object code that is not dependent on Python compilation flags.
517 : : */
518 : : PyAPI_FUNC(void) Py_IncRef(PyObject *);
519 : : PyAPI_FUNC(void) Py_DecRef(PyObject *);
520 : :
521 : : // Similar to Py_IncRef() and Py_DecRef() but the argument must be non-NULL.
522 : : // Private functions used by Py_INCREF() and Py_DECREF().
523 : : PyAPI_FUNC(void) _Py_IncRef(PyObject *);
524 : : PyAPI_FUNC(void) _Py_DecRef(PyObject *);
525 : :
526 : 161420248 : static inline void Py_INCREF(PyObject *op)
527 : : {
528 : : #if defined(Py_REF_DEBUG) && defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030A0000
529 : : // Stable ABI for Python 3.10 built in debug mode.
530 : : _Py_IncRef(op);
531 : : #else
532 : : _Py_INCREF_STAT_INC();
533 : : // Non-limited C API and limited C API for Python 3.9 and older access
534 : : // directly PyObject.ob_refcnt.
535 : : #ifdef Py_REF_DEBUG
536 : : _Py_INC_REFTOTAL();
537 : : #endif // Py_REF_DEBUG
538 : 161420248 : op->ob_refcnt++;
539 : : #endif
540 : 161420248 : }
541 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
542 : : # define Py_INCREF(op) Py_INCREF(_PyObject_CAST(op))
543 : : #endif
544 : :
545 : : #if defined(Py_REF_DEBUG) && defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030A0000
546 : : // Stable ABI for limited C API version 3.10 of Python debug build
547 : : static inline void Py_DECREF(PyObject *op) {
548 : : _Py_DecRef(op);
549 : : }
550 : : #define Py_DECREF(op) Py_DECREF(_PyObject_CAST(op))
551 : :
552 : : #elif defined(Py_REF_DEBUG)
553 : : static inline void Py_DECREF(const char *filename, int lineno, PyObject *op)
554 : : {
555 : : _Py_DECREF_STAT_INC();
556 : : _Py_DEC_REFTOTAL();
557 : : if (--op->ob_refcnt != 0) {
558 : : if (op->ob_refcnt < 0) {
559 : : _Py_NegativeRefcount(filename, lineno, op);
560 : : }
561 : : }
562 : : else {
563 : : _Py_Dealloc(op);
564 : : }
565 : : }
566 : : #define Py_DECREF(op) Py_DECREF(__FILE__, __LINE__, _PyObject_CAST(op))
567 : :
568 : : #else
569 : 112122299 : static inline void Py_DECREF(PyObject *op)
570 : : {
571 : : _Py_DECREF_STAT_INC();
572 : : // Non-limited C API and limited C API for Python 3.9 and older access
573 : : // directly PyObject.ob_refcnt.
574 [ + + ]: 112122299 : if (--op->ob_refcnt == 0) {
575 : 18024377 : _Py_Dealloc(op);
576 : : }
577 : 112122299 : }
578 : : #define Py_DECREF(op) Py_DECREF(_PyObject_CAST(op))
579 : : #endif
580 : :
581 : : #undef _Py_INC_REFTOTAL
582 : : #undef _Py_DEC_REFTOTAL
583 : :
584 : :
585 : : /* Safely decref `op` and set `op` to NULL, especially useful in tp_clear
586 : : * and tp_dealloc implementations.
587 : : *
588 : : * Note that "the obvious" code can be deadly:
589 : : *
590 : : * Py_XDECREF(op);
591 : : * op = NULL;
592 : : *
593 : : * Typically, `op` is something like self->containee, and `self` is done
594 : : * using its `containee` member. In the code sequence above, suppose
595 : : * `containee` is non-NULL with a refcount of 1. Its refcount falls to
596 : : * 0 on the first line, which can trigger an arbitrary amount of code,
597 : : * possibly including finalizers (like __del__ methods or weakref callbacks)
598 : : * coded in Python, which in turn can release the GIL and allow other threads
599 : : * to run, etc. Such code may even invoke methods of `self` again, or cause
600 : : * cyclic gc to trigger, but-- oops! --self->containee still points to the
601 : : * object being torn down, and it may be in an insane state while being torn
602 : : * down. This has in fact been a rich historic source of miserable (rare &
603 : : * hard-to-diagnose) segfaulting (and other) bugs.
604 : : *
605 : : * The safe way is:
606 : : *
607 : : * Py_CLEAR(op);
608 : : *
609 : : * That arranges to set `op` to NULL _before_ decref'ing, so that any code
610 : : * triggered as a side-effect of `op` getting torn down no longer believes
611 : : * `op` points to a valid object.
612 : : *
613 : : * There are cases where it's safe to use the naive code, but they're brittle.
614 : : * For example, if `op` points to a Python integer, you know that destroying
615 : : * one of those can't cause problems -- but in part that relies on that
616 : : * Python integers aren't currently weakly referencable. Best practice is
617 : : * to use Py_CLEAR() even if you can't think of a reason for why you need to.
618 : : *
619 : : * gh-98724: Use a temporary variable to only evaluate the macro argument once,
620 : : * to avoid the duplication of side effects if the argument has side effects.
621 : : *
622 : : * gh-99701: If the PyObject* type is used with casting arguments to PyObject*,
623 : : * the code can be miscompiled with strict aliasing because of type punning.
624 : : * With strict aliasing, a compiler considers that two pointers of different
625 : : * types cannot read or write the same memory which enables optimization
626 : : * opportunities.
627 : : *
628 : : * If available, use _Py_TYPEOF() to use the 'op' type for temporary variables,
629 : : * and so avoid type punning. Otherwise, use memcpy() which causes type erasure
630 : : * and so prevents the compiler to reuse an old cached 'op' value after
631 : : * Py_CLEAR().
632 : : */
633 : : #ifdef _Py_TYPEOF
634 : : #define Py_CLEAR(op) \
635 : : do { \
636 : : _Py_TYPEOF(op)* _tmp_op_ptr = &(op); \
637 : : _Py_TYPEOF(op) _tmp_old_op = (*_tmp_op_ptr); \
638 : : if (_tmp_old_op != NULL) { \
639 : : *_tmp_op_ptr = _Py_NULL; \
640 : : Py_DECREF(_tmp_old_op); \
641 : : } \
642 : : } while (0)
643 : : #else
644 : : #define Py_CLEAR(op) \
645 : : do { \
646 : : PyObject **_tmp_op_ptr = _Py_CAST(PyObject**, &(op)); \
647 : : PyObject *_tmp_old_op = (*_tmp_op_ptr); \
648 : : if (_tmp_old_op != NULL) { \
649 : : PyObject *_null_ptr = _Py_NULL; \
650 : : memcpy(_tmp_op_ptr, &_null_ptr, sizeof(PyObject*)); \
651 : : Py_DECREF(_tmp_old_op); \
652 : : } \
653 : : } while (0)
654 : : #endif
655 : :
656 : :
657 : : /* Function to use in case the object pointer can be NULL: */
658 : 7162978 : static inline void Py_XINCREF(PyObject *op)
659 : : {
660 [ + + ]: 7162978 : if (op != _Py_NULL) {
661 : 2901381 : Py_INCREF(op);
662 : : }
663 : 7162978 : }
664 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
665 : : # define Py_XINCREF(op) Py_XINCREF(_PyObject_CAST(op))
666 : : #endif
667 : :
668 : 72166708 : static inline void Py_XDECREF(PyObject *op)
669 : : {
670 [ + + ]: 72166708 : if (op != _Py_NULL) {
671 : 49898426 : Py_DECREF(op);
672 : : }
673 : 72166708 : }
674 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
675 : : # define Py_XDECREF(op) Py_XDECREF(_PyObject_CAST(op))
676 : : #endif
677 : :
678 : : // Create a new strong reference to an object:
679 : : // increment the reference count of the object and return the object.
680 : : PyAPI_FUNC(PyObject*) Py_NewRef(PyObject *obj);
681 : :
682 : : // Similar to Py_NewRef(), but the object can be NULL.
683 : : PyAPI_FUNC(PyObject*) Py_XNewRef(PyObject *obj);
684 : :
685 : 68133682 : static inline PyObject* _Py_NewRef(PyObject *obj)
686 : : {
687 : 68133682 : Py_INCREF(obj);
688 : 68133682 : return obj;
689 : : }
690 : :
691 : 5696057 : static inline PyObject* _Py_XNewRef(PyObject *obj)
692 : : {
693 : 5696057 : Py_XINCREF(obj);
694 : 5696057 : return obj;
695 : : }
696 : :
697 : : // Py_NewRef() and Py_XNewRef() are exported as functions for the stable ABI.
698 : : // Names overridden with macros by static inline functions for best
699 : : // performances.
700 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
701 : : # define Py_NewRef(obj) _Py_NewRef(_PyObject_CAST(obj))
702 : : # define Py_XNewRef(obj) _Py_XNewRef(_PyObject_CAST(obj))
703 : : #else
704 : : # define Py_NewRef(obj) _Py_NewRef(obj)
705 : : # define Py_XNewRef(obj) _Py_XNewRef(obj)
706 : : #endif
707 : :
708 : :
709 : : /*
710 : : _Py_NoneStruct is an object of undefined type which can be used in contexts
711 : : where NULL (nil) is not suitable (since NULL often means 'error').
712 : :
713 : : Don't forget to apply Py_INCREF() when returning this value!!!
714 : : */
715 : : PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
716 : : #define Py_None (&_Py_NoneStruct)
717 : :
718 : : // Test if an object is the None singleton, the same as "x is None" in Python.
719 : : PyAPI_FUNC(int) Py_IsNone(PyObject *x);
720 : : #define Py_IsNone(x) Py_Is((x), Py_None)
721 : :
722 : : /* Macro for returning Py_None from a function */
723 : : #define Py_RETURN_NONE return Py_NewRef(Py_None)
724 : :
725 : : /*
726 : : Py_NotImplemented is a singleton used to signal that an operation is
727 : : not implemented for a given type combination.
728 : : */
729 : : PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
730 : : #define Py_NotImplemented (&_Py_NotImplementedStruct)
731 : :
732 : : /* Macro for returning Py_NotImplemented from a function */
733 : : #define Py_RETURN_NOTIMPLEMENTED return Py_NewRef(Py_NotImplemented)
734 : :
735 : : /* Rich comparison opcodes */
736 : : #define Py_LT 0
737 : : #define Py_LE 1
738 : : #define Py_EQ 2
739 : : #define Py_NE 3
740 : : #define Py_GT 4
741 : : #define Py_GE 5
742 : :
743 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000
744 : : /* Result of calling PyIter_Send */
745 : : typedef enum {
746 : : PYGEN_RETURN = 0,
747 : : PYGEN_ERROR = -1,
748 : : PYGEN_NEXT = 1,
749 : : } PySendResult;
750 : : #endif
751 : :
752 : : /*
753 : : * Macro for implementing rich comparisons
754 : : *
755 : : * Needs to be a macro because any C-comparable type can be used.
756 : : */
757 : : #define Py_RETURN_RICHCOMPARE(val1, val2, op) \
758 : : do { \
759 : : switch (op) { \
760 : : case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
761 : : case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
762 : : case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
763 : : case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
764 : : case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
765 : : case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
766 : : default: \
767 : : Py_UNREACHABLE(); \
768 : : } \
769 : : } while (0)
770 : :
771 : :
772 : : /*
773 : : More conventions
774 : : ================
775 : :
776 : : Argument Checking
777 : : -----------------
778 : :
779 : : Functions that take objects as arguments normally don't check for nil
780 : : arguments, but they do check the type of the argument, and return an
781 : : error if the function doesn't apply to the type.
782 : :
783 : : Failure Modes
784 : : -------------
785 : :
786 : : Functions may fail for a variety of reasons, including running out of
787 : : memory. This is communicated to the caller in two ways: an error string
788 : : is set (see errors.h), and the function result differs: functions that
789 : : normally return a pointer return NULL for failure, functions returning
790 : : an integer return -1 (which could be a legal return value too!), and
791 : : other functions return 0 for success and -1 for failure.
792 : : Callers should always check for errors before using the result. If
793 : : an error was set, the caller must either explicitly clear it, or pass
794 : : the error on to its caller.
795 : :
796 : : Reference Counts
797 : : ----------------
798 : :
799 : : It takes a while to get used to the proper usage of reference counts.
800 : :
801 : : Functions that create an object set the reference count to 1; such new
802 : : objects must be stored somewhere or destroyed again with Py_DECREF().
803 : : Some functions that 'store' objects, such as PyTuple_SetItem() and
804 : : PyList_SetItem(),
805 : : don't increment the reference count of the object, since the most
806 : : frequent use is to store a fresh object. Functions that 'retrieve'
807 : : objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
808 : : don't increment
809 : : the reference count, since most frequently the object is only looked at
810 : : quickly. Thus, to retrieve an object and store it again, the caller
811 : : must call Py_INCREF() explicitly.
812 : :
813 : : NOTE: functions that 'consume' a reference count, like
814 : : PyList_SetItem(), consume the reference even if the object wasn't
815 : : successfully stored, to simplify error handling.
816 : :
817 : : It seems attractive to make other functions that take an object as
818 : : argument consume a reference count; however, this may quickly get
819 : : confusing (even the current practice is already confusing). Consider
820 : : it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
821 : : times.
822 : : */
823 : :
824 : : #ifndef Py_LIMITED_API
825 : : # define Py_CPYTHON_OBJECT_H
826 : : # include "cpython/object.h"
827 : : # undef Py_CPYTHON_OBJECT_H
828 : : #endif
829 : :
830 : :
831 : : static inline int
832 : 92253693 : PyType_HasFeature(PyTypeObject *type, unsigned long feature)
833 : : {
834 : : unsigned long flags;
835 : : #ifdef Py_LIMITED_API
836 : : // PyTypeObject is opaque in the limited C API
837 : 0 : flags = PyType_GetFlags(type);
838 : : #else
839 : 92253693 : flags = type->tp_flags;
840 : : #endif
841 : 92253693 : return ((flags & feature) != 0);
842 : : }
843 : :
844 : : #define PyType_FastSubclass(type, flag) PyType_HasFeature((type), (flag))
845 : :
846 : 4180654 : static inline int PyType_Check(PyObject *op) {
847 : 4180654 : return PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS);
848 : : }
849 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
850 : : # define PyType_Check(op) PyType_Check(_PyObject_CAST(op))
851 : : #endif
852 : :
853 : : #define _PyType_CAST(op) \
854 : : (assert(PyType_Check(op)), _Py_CAST(PyTypeObject*, (op)))
855 : :
856 : 152457 : static inline int PyType_CheckExact(PyObject *op) {
857 : 152457 : return Py_IS_TYPE(op, &PyType_Type);
858 : : }
859 : : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
860 : : # define PyType_CheckExact(op) PyType_CheckExact(_PyObject_CAST(op))
861 : : #endif
862 : :
863 : : #ifdef __cplusplus
864 : : }
865 : : #endif
866 : : #endif // !Py_OBJECT_H
|