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 : /* Py_DEBUG implies Py_REF_DEBUG. */
55 : #if defined(Py_DEBUG) && !defined(Py_REF_DEBUG)
56 : # define Py_REF_DEBUG
57 : #endif
58 :
59 : /* PyObject_HEAD defines the initial segment of every PyObject. */
60 : #define PyObject_HEAD PyObject ob_base;
61 :
62 : /*
63 : Immortalization:
64 :
65 : The following indicates the immortalization strategy depending on the amount
66 : of available bits in the reference count field. All strategies are backwards
67 : compatible but the specific reference count value or immortalization check
68 : might change depending on the specializations for the underlying system.
69 :
70 : Proper deallocation of immortal instances requires distinguishing between
71 : statically allocated immortal instances vs those promoted by the runtime to be
72 : immortal. The latter should be the only instances that require
73 : cleanup during runtime finalization.
74 : */
75 :
76 : #if SIZEOF_VOID_P > 4
77 : /*
78 : In 64+ bit systems, an object will be marked as immortal by setting all of the
79 : lower 32 bits of the reference count field, which is equal to: 0xFFFFFFFF
80 :
81 : Using the lower 32 bits makes the value backwards compatible by allowing
82 : C-Extensions without the updated checks in Py_INCREF and Py_DECREF to safely
83 : increase and decrease the objects reference count. The object would lose its
84 : immortality, but the execution would still be correct.
85 :
86 : Reference count increases will use saturated arithmetic, taking advantage of
87 : having all the lower 32 bits set, which will avoid the reference count to go
88 : beyond the refcount limit. Immortality checks for reference count decreases will
89 : be done by checking the bit sign flag in the lower 32 bits.
90 : */
91 : #define _Py_IMMORTAL_REFCNT _Py_CAST(Py_ssize_t, UINT_MAX)
92 :
93 : #else
94 : /*
95 : In 32 bit systems, an object will be marked as immortal by setting all of the
96 : lower 30 bits of the reference count field, which is equal to: 0x3FFFFFFF
97 :
98 : Using the lower 30 bits makes the value backwards compatible by allowing
99 : C-Extensions without the updated checks in Py_INCREF and Py_DECREF to safely
100 : increase and decrease the objects reference count. The object would lose its
101 : immortality, but the execution would still be correct.
102 :
103 : Reference count increases and decreases will first go through an immortality
104 : check by comparing the reference count field to the immortality reference count.
105 : */
106 : #define _Py_IMMORTAL_REFCNT _Py_CAST(Py_ssize_t, UINT_MAX >> 2)
107 : #endif
108 :
109 : // Py_GIL_DISABLED builds indicate immortal objects using `ob_ref_local`, which is
110 : // always 32-bits.
111 : #ifdef Py_GIL_DISABLED
112 : #define _Py_IMMORTAL_REFCNT_LOCAL UINT32_MAX
113 : #endif
114 :
115 : // Kept for backward compatibility. It was needed by Py_TRACE_REFS build.
116 : #define _PyObject_EXTRA_INIT
117 :
118 : /* Make all uses of PyObject_HEAD_INIT immortal.
119 : *
120 : * Statically allocated objects might be shared between
121 : * interpreters, so must be marked as immortal.
122 : */
123 : #if defined(Py_GIL_DISABLED)
124 : #define PyObject_HEAD_INIT(type) \
125 : { \
126 : 0, \
127 : 0, \
128 : { 0 }, \
129 : 0, \
130 : _Py_IMMORTAL_REFCNT_LOCAL, \
131 : 0, \
132 : (type), \
133 : },
134 : #else
135 : #define PyObject_HEAD_INIT(type) \
136 : { \
137 : { _Py_IMMORTAL_REFCNT }, \
138 : (type) \
139 : },
140 : #endif
141 :
142 : #define PyVarObject_HEAD_INIT(type, size) \
143 : { \
144 : PyObject_HEAD_INIT(type) \
145 : (size) \
146 : },
147 :
148 : /* PyObject_VAR_HEAD defines the initial segment of all variable-size
149 : * container objects. These end with a declaration of an array with 1
150 : * element, but enough space is malloc'ed so that the array actually
151 : * has room for ob_size elements. Note that ob_size is an element count,
152 : * not necessarily a byte count.
153 : */
154 : #define PyObject_VAR_HEAD PyVarObject ob_base;
155 : #define Py_INVALID_SIZE (Py_ssize_t)-1
156 :
157 : /* PyObjects are given a minimum alignment so that the least significant bits
158 : * of an object pointer become available for other purposes.
159 : */
160 : #define _PyObject_ALIGNMENT_SHIFT 2
161 :
162 : /* Nothing is actually declared to be a PyObject, but every pointer to
163 : * a Python object can be cast to a PyObject*. This is inheritance built
164 : * by hand. Similarly every pointer to a variable-size Python object can,
165 : * in addition, be cast to PyVarObject*.
166 : */
167 : #ifndef Py_GIL_DISABLED
168 : struct _object {
169 : #if (defined(__GNUC__) || defined(__clang__)) \
170 : && !(defined __STDC_VERSION__ && __STDC_VERSION__ >= 201112L)
171 : // On C99 and older, anonymous union is a GCC and clang extension
172 : __extension__
173 : #endif
174 : #ifdef _MSC_VER
175 : // Ignore MSC warning C4201: "nonstandard extension used:
176 : // nameless struct/union"
177 : __pragma(warning(push))
178 : __pragma(warning(disable: 4201))
179 : #endif
180 : union {
181 : Py_ssize_t ob_refcnt;
182 : #if SIZEOF_VOID_P > 4
183 : PY_UINT32_T ob_refcnt_split[2];
184 : #endif
185 : };
186 : #ifdef _MSC_VER
187 : __pragma(warning(pop))
188 : #endif
189 :
190 : PyTypeObject *ob_type;
191 : } Py_ALIGNED(1 << _PyObject_ALIGNMENT_SHIFT);
192 : #else
193 : // Objects that are not owned by any thread use a thread id (tid) of zero.
194 : // This includes both immortal objects and objects whose reference count
195 : // fields have been merged.
196 : #define _Py_UNOWNED_TID 0
197 :
198 : // The shared reference count uses the two least-significant bits to store
199 : // flags. The remaining bits are used to store the reference count.
200 : #define _Py_REF_SHARED_SHIFT 2
201 : #define _Py_REF_SHARED_FLAG_MASK 0x3
202 :
203 : // The shared flags are initialized to zero.
204 : #define _Py_REF_SHARED_INIT 0x0
205 : #define _Py_REF_MAYBE_WEAKREF 0x1
206 : #define _Py_REF_QUEUED 0x2
207 : #define _Py_REF_MERGED 0x3
208 :
209 : // Create a shared field from a refcnt and desired flags
210 : #define _Py_REF_SHARED(refcnt, flags) (((refcnt) << _Py_REF_SHARED_SHIFT) + (flags))
211 :
212 : struct _object {
213 : // ob_tid stores the thread id (or zero). It is also used by the GC and the
214 : // trashcan mechanism as a linked list pointer and by the GC to store the
215 : // computed "gc_refs" refcount.
216 : uintptr_t ob_tid;
217 : uint16_t _padding;
218 : PyMutex ob_mutex; // per-object lock
219 : uint8_t ob_gc_bits; // gc-related state
220 : uint32_t ob_ref_local; // local reference count
221 : Py_ssize_t ob_ref_shared; // shared (atomic) reference count
222 : PyTypeObject *ob_type;
223 : } Py_ALIGNED(1 << _PyObject_ALIGNMENT_SHIFT);
224 : #endif
225 :
226 : /* Cast argument to PyObject* type. */
227 : #define _PyObject_CAST(op) _Py_CAST(PyObject*, (op))
228 :
229 : typedef struct {
230 : PyObject ob_base;
231 : Py_ssize_t ob_size; /* Number of items in variable part */
232 : } PyVarObject;
233 :
234 : /* Cast argument to PyVarObject* type. */
235 : #define _PyVarObject_CAST(op) _Py_CAST(PyVarObject*, (op))
236 :
237 :
238 : // Test if the 'x' object is the 'y' object, the same as "x is y" in Python.
239 : PyAPI_FUNC(int) Py_Is(PyObject *x, PyObject *y);
240 : #define Py_Is(x, y) ((x) == (y))
241 :
242 : #if defined(Py_GIL_DISABLED) && !defined(Py_LIMITED_API)
243 : PyAPI_FUNC(uintptr_t) _Py_GetThreadLocal_Addr(void);
244 :
245 : static inline uintptr_t
246 : _Py_ThreadId(void)
247 : {
248 : uintptr_t tid;
249 : #if defined(_MSC_VER) && defined(_M_X64)
250 : tid = __readgsqword(48);
251 : #elif defined(_MSC_VER) && defined(_M_IX86)
252 : tid = __readfsdword(24);
253 : #elif defined(_MSC_VER) && defined(_M_ARM64)
254 : tid = __getReg(18);
255 : #elif defined(__MINGW32__) && defined(_M_X64)
256 : tid = __readgsqword(48);
257 : #elif defined(__MINGW32__) && defined(_M_IX86)
258 : tid = __readfsdword(24);
259 : #elif defined(__MINGW32__) && defined(_M_ARM64)
260 : tid = __getReg(18);
261 : #elif defined(__i386__)
262 : __asm__("movl %%gs:0, %0" : "=r" (tid)); // 32-bit always uses GS
263 : #elif defined(__MACH__) && defined(__x86_64__)
264 : __asm__("movq %%gs:0, %0" : "=r" (tid)); // x86_64 macOSX uses GS
265 : #elif defined(__x86_64__)
266 : __asm__("movq %%fs:0, %0" : "=r" (tid)); // x86_64 Linux, BSD uses FS
267 : #elif defined(__arm__) && __ARM_ARCH >= 7
268 : __asm__ ("mrc p15, 0, %0, c13, c0, 3\nbic %0, %0, #3" : "=r" (tid));
269 : #elif defined(__aarch64__) && defined(__APPLE__)
270 : __asm__ ("mrs %0, tpidrro_el0" : "=r" (tid));
271 : #elif defined(__aarch64__)
272 : __asm__ ("mrs %0, tpidr_el0" : "=r" (tid));
273 : #elif defined(__powerpc64__)
274 : #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer)
275 : tid = (uintptr_t)__builtin_thread_pointer();
276 : #else
277 : // r13 is reserved for use as system thread ID by the Power 64-bit ABI.
278 : register uintptr_t tp __asm__ ("r13");
279 : __asm__("" : "=r" (tp));
280 : tid = tp;
281 : #endif
282 : #elif defined(__powerpc__)
283 : #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer)
284 : tid = (uintptr_t)__builtin_thread_pointer();
285 : #else
286 : // r2 is reserved for use as system thread ID by the Power 32-bit ABI.
287 : register uintptr_t tp __asm__ ("r2");
288 : __asm__ ("" : "=r" (tp));
289 : tid = tp;
290 : #endif
291 : #elif defined(__s390__) && defined(__GNUC__)
292 : // Both GCC and Clang have supported __builtin_thread_pointer
293 : // for s390 from long time ago.
294 : tid = (uintptr_t)__builtin_thread_pointer();
295 : #elif defined(__riscv)
296 : #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer)
297 : tid = (uintptr_t)__builtin_thread_pointer();
298 : #else
299 : // tp is Thread Pointer provided by the RISC-V ABI.
300 : __asm__ ("mv %0, tp" : "=r" (tid));
301 : #endif
302 : #else
303 : // Fallback to a portable implementation if we do not have a faster
304 : // platform-specific implementation.
305 : tid = _Py_GetThreadLocal_Addr();
306 : #endif
307 : return tid;
308 : }
309 :
310 : static inline Py_ALWAYS_INLINE int
311 : _Py_IsOwnedByCurrentThread(PyObject *ob)
312 : {
313 : #ifdef _Py_THREAD_SANITIZER
314 : return _Py_atomic_load_uintptr_relaxed(&ob->ob_tid) == _Py_ThreadId();
315 : #else
316 : return ob->ob_tid == _Py_ThreadId();
317 : #endif
318 : }
319 : #endif
320 :
321 : static inline Py_ssize_t Py_REFCNT(PyObject *ob) {
322 : #if !defined(Py_GIL_DISABLED)
323 : return ob->ob_refcnt;
324 : #else
325 : uint32_t local = _Py_atomic_load_uint32_relaxed(&ob->ob_ref_local);
326 : if (local == _Py_IMMORTAL_REFCNT_LOCAL) {
327 : return _Py_IMMORTAL_REFCNT;
328 : }
329 : Py_ssize_t shared = _Py_atomic_load_ssize_relaxed(&ob->ob_ref_shared);
330 : return _Py_STATIC_CAST(Py_ssize_t, local) +
331 : Py_ARITHMETIC_RIGHT_SHIFT(Py_ssize_t, shared, _Py_REF_SHARED_SHIFT);
332 : #endif
333 : }
334 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
335 : # define Py_REFCNT(ob) Py_REFCNT(_PyObject_CAST(ob))
336 : #endif
337 :
338 :
339 : // bpo-39573: The Py_SET_TYPE() function must be used to set an object type.
340 5857 : static inline PyTypeObject* Py_TYPE(PyObject *ob) {
341 5857 : return ob->ob_type;
342 : }
343 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
344 : # define Py_TYPE(ob) Py_TYPE(_PyObject_CAST(ob))
345 : #endif
346 :
347 : PyAPI_DATA(PyTypeObject) PyLong_Type;
348 : PyAPI_DATA(PyTypeObject) PyBool_Type;
349 :
350 : // bpo-39573: The Py_SET_SIZE() function must be used to set an object size.
351 : static inline Py_ssize_t Py_SIZE(PyObject *ob) {
352 : assert(ob->ob_type != &PyLong_Type);
353 : assert(ob->ob_type != &PyBool_Type);
354 : return _PyVarObject_CAST(ob)->ob_size;
355 : }
356 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
357 : # define Py_SIZE(ob) Py_SIZE(_PyObject_CAST(ob))
358 : #endif
359 :
360 : static inline Py_ALWAYS_INLINE int _Py_IsImmortal(PyObject *op)
361 : {
362 : #if defined(Py_GIL_DISABLED)
363 : return (_Py_atomic_load_uint32_relaxed(&op->ob_ref_local) ==
364 : _Py_IMMORTAL_REFCNT_LOCAL);
365 : #elif SIZEOF_VOID_P > 4
366 19700 : return (_Py_CAST(PY_INT32_T, op->ob_refcnt) < 0);
367 : #else
368 : return (op->ob_refcnt == _Py_IMMORTAL_REFCNT);
369 : #endif
370 : }
371 : #define _Py_IsImmortal(op) _Py_IsImmortal(_PyObject_CAST(op))
372 :
373 1264 : static inline int Py_IS_TYPE(PyObject *ob, PyTypeObject *type) {
374 1264 : return Py_TYPE(ob) == type;
375 : }
376 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
377 : # define Py_IS_TYPE(ob, type) Py_IS_TYPE(_PyObject_CAST(ob), (type))
378 : #endif
379 :
380 :
381 : // Py_SET_REFCNT() implementation for stable ABI
382 : PyAPI_FUNC(void) _Py_SetRefcnt(PyObject *ob, Py_ssize_t refcnt);
383 :
384 : static inline void Py_SET_REFCNT(PyObject *ob, Py_ssize_t refcnt) {
385 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030d0000
386 : // Stable ABI implements Py_SET_REFCNT() as a function call
387 : // on limited C API version 3.13 and newer.
388 : _Py_SetRefcnt(ob, refcnt);
389 : #else
390 : // This immortal check is for code that is unaware of immortal objects.
391 : // The runtime tracks these objects and we should avoid as much
392 : // as possible having extensions inadvertently change the refcnt
393 : // of an immortalized object.
394 : if (_Py_IsImmortal(ob)) {
395 : return;
396 : }
397 :
398 : #ifndef Py_GIL_DISABLED
399 : ob->ob_refcnt = refcnt;
400 : #else
401 : if (_Py_IsOwnedByCurrentThread(ob)) {
402 : if ((size_t)refcnt > (size_t)UINT32_MAX) {
403 : // On overflow, make the object immortal
404 : ob->ob_tid = _Py_UNOWNED_TID;
405 : ob->ob_ref_local = _Py_IMMORTAL_REFCNT_LOCAL;
406 : ob->ob_ref_shared = 0;
407 : }
408 : else {
409 : // Set local refcount to desired refcount and shared refcount
410 : // to zero, but preserve the shared refcount flags.
411 : ob->ob_ref_local = _Py_STATIC_CAST(uint32_t, refcnt);
412 : ob->ob_ref_shared &= _Py_REF_SHARED_FLAG_MASK;
413 : }
414 : }
415 : else {
416 : // Set local refcount to zero and shared refcount to desired refcount.
417 : // Mark the object as merged.
418 : ob->ob_tid = _Py_UNOWNED_TID;
419 : ob->ob_ref_local = 0;
420 : ob->ob_ref_shared = _Py_REF_SHARED(refcnt, _Py_REF_MERGED);
421 : }
422 : #endif // Py_GIL_DISABLED
423 : #endif // Py_LIMITED_API+0 < 0x030d0000
424 : }
425 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
426 : # define Py_SET_REFCNT(ob, refcnt) Py_SET_REFCNT(_PyObject_CAST(ob), (refcnt))
427 : #endif
428 :
429 :
430 : static inline void Py_SET_TYPE(PyObject *ob, PyTypeObject *type) {
431 : ob->ob_type = type;
432 : }
433 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
434 : # define Py_SET_TYPE(ob, type) Py_SET_TYPE(_PyObject_CAST(ob), type)
435 : #endif
436 :
437 : static inline void Py_SET_SIZE(PyVarObject *ob, Py_ssize_t size) {
438 : assert(ob->ob_base.ob_type != &PyLong_Type);
439 : assert(ob->ob_base.ob_type != &PyBool_Type);
440 : #ifdef Py_GIL_DISABLED
441 : _Py_atomic_store_ssize_relaxed(&ob->ob_size, size);
442 : #else
443 : ob->ob_size = size;
444 : #endif
445 : }
446 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
447 : # define Py_SET_SIZE(ob, size) Py_SET_SIZE(_PyVarObject_CAST(ob), (size))
448 : #endif
449 :
450 :
451 : /*
452 : Type objects contain a string containing the type name (to help somewhat
453 : in debugging), the allocation parameters (see PyObject_New() and
454 : PyObject_NewVar()),
455 : and methods for accessing objects of the type. Methods are optional, a
456 : nil pointer meaning that particular kind of access is not available for
457 : this type. The Py_DECREF() macro uses the tp_dealloc method without
458 : checking for a nil pointer; it should always be implemented except if
459 : the implementation can guarantee that the reference count will never
460 : reach zero (e.g., for statically allocated type objects).
461 :
462 : NB: the methods for certain type groups are now contained in separate
463 : method blocks.
464 : */
465 :
466 : typedef PyObject * (*unaryfunc)(PyObject *);
467 : typedef PyObject * (*binaryfunc)(PyObject *, PyObject *);
468 : typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *);
469 : typedef int (*inquiry)(PyObject *);
470 : typedef Py_ssize_t (*lenfunc)(PyObject *);
471 : typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t);
472 : typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t);
473 : typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *);
474 : typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *);
475 : typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *);
476 :
477 : typedef int (*objobjproc)(PyObject *, PyObject *);
478 : typedef int (*visitproc)(PyObject *, void *);
479 : typedef int (*traverseproc)(PyObject *, visitproc, void *);
480 :
481 :
482 : typedef void (*freefunc)(void *);
483 : typedef void (*destructor)(PyObject *);
484 : typedef PyObject *(*getattrfunc)(PyObject *, char *);
485 : typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
486 : typedef int (*setattrfunc)(PyObject *, char *, PyObject *);
487 : typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *);
488 : typedef PyObject *(*reprfunc)(PyObject *);
489 : typedef Py_hash_t (*hashfunc)(PyObject *);
490 : typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int);
491 : typedef PyObject *(*getiterfunc) (PyObject *);
492 : typedef PyObject *(*iternextfunc) (PyObject *);
493 : typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *);
494 : typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *);
495 : typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
496 : typedef PyObject *(*newfunc)(PyTypeObject *, PyObject *, PyObject *);
497 : typedef PyObject *(*allocfunc)(PyTypeObject *, Py_ssize_t);
498 :
499 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030c0000 // 3.12
500 : typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args,
501 : size_t nargsf, PyObject *kwnames);
502 : #endif
503 :
504 : typedef struct{
505 : int slot; /* slot id, see below */
506 : void *pfunc; /* function pointer */
507 : } PyType_Slot;
508 :
509 : typedef struct{
510 : const char* name;
511 : int basicsize;
512 : int itemsize;
513 : unsigned int flags;
514 : PyType_Slot *slots; /* terminated by slot==0. */
515 : } PyType_Spec;
516 :
517 : PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*);
518 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
519 : PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*);
520 : #endif
521 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000
522 : PyAPI_FUNC(void*) PyType_GetSlot(PyTypeObject*, int);
523 : #endif
524 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000
525 : PyAPI_FUNC(PyObject*) PyType_FromModuleAndSpec(PyObject *, PyType_Spec *, PyObject *);
526 : PyAPI_FUNC(PyObject *) PyType_GetModule(PyTypeObject *);
527 : PyAPI_FUNC(void *) PyType_GetModuleState(PyTypeObject *);
528 : #endif
529 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030B0000
530 : PyAPI_FUNC(PyObject *) PyType_GetName(PyTypeObject *);
531 : PyAPI_FUNC(PyObject *) PyType_GetQualName(PyTypeObject *);
532 : #endif
533 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030D0000
534 : PyAPI_FUNC(PyObject *) PyType_GetFullyQualifiedName(PyTypeObject *type);
535 : PyAPI_FUNC(PyObject *) PyType_GetModuleName(PyTypeObject *type);
536 : #endif
537 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
538 : PyAPI_FUNC(PyObject *) PyType_FromMetaclass(PyTypeObject*, PyObject*, PyType_Spec*, PyObject*);
539 : PyAPI_FUNC(void *) PyObject_GetTypeData(PyObject *obj, PyTypeObject *cls);
540 : PyAPI_FUNC(Py_ssize_t) PyType_GetTypeDataSize(PyTypeObject *cls);
541 : #endif
542 :
543 : /* Generic type check */
544 : PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *);
545 :
546 1243 : static inline int PyObject_TypeCheck(PyObject *ob, PyTypeObject *type) {
547 1243 : return Py_IS_TYPE(ob, type) || PyType_IsSubtype(Py_TYPE(ob), type);
548 : }
549 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
550 : # define PyObject_TypeCheck(ob, type) PyObject_TypeCheck(_PyObject_CAST(ob), (type))
551 : #endif
552 :
553 : PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */
554 : PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */
555 : PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */
556 :
557 : PyAPI_FUNC(unsigned long) PyType_GetFlags(PyTypeObject*);
558 :
559 : PyAPI_FUNC(int) PyType_Ready(PyTypeObject *);
560 : PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t);
561 : PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *,
562 : PyObject *, PyObject *);
563 : PyAPI_FUNC(unsigned int) PyType_ClearCache(void);
564 : PyAPI_FUNC(void) PyType_Modified(PyTypeObject *);
565 :
566 : /* Generic operations on objects */
567 : PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
568 : PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
569 : PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *);
570 : PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *);
571 : PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
572 : PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
573 : PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *);
574 : PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *);
575 : PyAPI_FUNC(int) PyObject_DelAttrString(PyObject *v, const char *name);
576 : PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *);
577 : PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
578 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
579 : PyAPI_FUNC(int) PyObject_GetOptionalAttr(PyObject *, PyObject *, PyObject **);
580 : PyAPI_FUNC(int) PyObject_GetOptionalAttrString(PyObject *, const char *, PyObject **);
581 : #endif
582 : PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
583 : PyAPI_FUNC(int) PyObject_DelAttr(PyObject *v, PyObject *name);
584 : PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
585 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
586 : PyAPI_FUNC(int) PyObject_HasAttrWithError(PyObject *, PyObject *);
587 : PyAPI_FUNC(int) PyObject_HasAttrStringWithError(PyObject *, const char *);
588 : #endif
589 : PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *);
590 : PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
591 : PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, PyObject *, PyObject *);
592 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
593 : PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *);
594 : #endif
595 : PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *);
596 : PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *);
597 : PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
598 : PyAPI_FUNC(int) PyObject_Not(PyObject *);
599 : PyAPI_FUNC(int) PyCallable_Check(PyObject *);
600 : PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
601 :
602 : /* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a
603 : list of strings. PyObject_Dir(NULL) is like builtins.dir(),
604 : returning the names of the current locals. In this case, if there are
605 : no current locals, NULL is returned, and PyErr_Occurred() is false.
606 : */
607 : PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
608 :
609 : /* Helpers for printing recursive container types */
610 : PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
611 : PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
612 :
613 : /* Flag bits for printing: */
614 : #define Py_PRINT_RAW 1 /* No string quotes etc. */
615 :
616 : /*
617 : Type flags (tp_flags)
618 :
619 : These flags are used to change expected features and behavior for a
620 : particular type.
621 :
622 : Arbitration of the flag bit positions will need to be coordinated among
623 : all extension writers who publicly release their extensions (this will
624 : be fewer than you might expect!).
625 :
626 : Most flags were removed as of Python 3.0 to make room for new flags. (Some
627 : flags are not for backwards compatibility but to indicate the presence of an
628 : optional feature; these flags remain of course.)
629 :
630 : Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
631 :
632 : Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
633 : given type object has a specified feature.
634 : */
635 :
636 : #ifndef Py_LIMITED_API
637 :
638 : /* Track types initialized using _PyStaticType_InitBuiltin(). */
639 : #define _Py_TPFLAGS_STATIC_BUILTIN (1 << 1)
640 :
641 : /* The values array is placed inline directly after the rest of
642 : * the object. Implies Py_TPFLAGS_HAVE_GC.
643 : */
644 : #define Py_TPFLAGS_INLINE_VALUES (1 << 2)
645 :
646 : /* Placement of weakref pointers are managed by the VM, not by the type.
647 : * The VM will automatically set tp_weaklistoffset.
648 : */
649 : #define Py_TPFLAGS_MANAGED_WEAKREF (1 << 3)
650 :
651 : /* Placement of dict (and values) pointers are managed by the VM, not by the type.
652 : * The VM will automatically set tp_dictoffset. Implies Py_TPFLAGS_HAVE_GC.
653 : */
654 : #define Py_TPFLAGS_MANAGED_DICT (1 << 4)
655 :
656 : #define Py_TPFLAGS_PREHEADER (Py_TPFLAGS_MANAGED_WEAKREF | Py_TPFLAGS_MANAGED_DICT)
657 :
658 : /* Set if instances of the type object are treated as sequences for pattern matching */
659 : #define Py_TPFLAGS_SEQUENCE (1 << 5)
660 : /* Set if instances of the type object are treated as mappings for pattern matching */
661 : #define Py_TPFLAGS_MAPPING (1 << 6)
662 : #endif
663 :
664 : /* Disallow creating instances of the type: set tp_new to NULL and don't create
665 : * the "__new__" key in the type dictionary. */
666 : #define Py_TPFLAGS_DISALLOW_INSTANTIATION (1UL << 7)
667 :
668 : /* Set if the type object is immutable: type attributes cannot be set nor deleted */
669 : #define Py_TPFLAGS_IMMUTABLETYPE (1UL << 8)
670 :
671 : /* Set if the type object is dynamically allocated */
672 : #define Py_TPFLAGS_HEAPTYPE (1UL << 9)
673 :
674 : /* Set if the type allows subclassing */
675 : #define Py_TPFLAGS_BASETYPE (1UL << 10)
676 :
677 : /* Set if the type implements the vectorcall protocol (PEP 590) */
678 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
679 : #define Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11)
680 : #ifndef Py_LIMITED_API
681 : // Backwards compatibility alias for API that was provisional in Python 3.8
682 : #define _Py_TPFLAGS_HAVE_VECTORCALL Py_TPFLAGS_HAVE_VECTORCALL
683 : #endif
684 : #endif
685 :
686 : /* Set if the type is 'ready' -- fully initialized */
687 : #define Py_TPFLAGS_READY (1UL << 12)
688 :
689 : /* Set while the type is being 'readied', to prevent recursive ready calls */
690 : #define Py_TPFLAGS_READYING (1UL << 13)
691 :
692 : /* Objects support garbage collection (see objimpl.h) */
693 : #define Py_TPFLAGS_HAVE_GC (1UL << 14)
694 :
695 : /* These two bits are preserved for Stackless Python, next after this is 17 */
696 : #ifdef STACKLESS
697 : #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15)
698 : #else
699 : #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
700 : #endif
701 :
702 : /* Objects behave like an unbound method */
703 : #define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17)
704 :
705 : /* Unused. Legacy flag */
706 : #define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19)
707 :
708 : /* Type is abstract and cannot be instantiated */
709 : #define Py_TPFLAGS_IS_ABSTRACT (1UL << 20)
710 :
711 : // This undocumented flag gives certain built-ins their unique pattern-matching
712 : // behavior, which allows a single positional subpattern to match against the
713 : // subject itself (rather than a mapped attribute on it):
714 : #define _Py_TPFLAGS_MATCH_SELF (1UL << 22)
715 :
716 : /* Items (ob_size*tp_itemsize) are found at the end of an instance's memory */
717 : #define Py_TPFLAGS_ITEMS_AT_END (1UL << 23)
718 :
719 : /* These flags are used to determine if a type is a subclass. */
720 : #define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24)
721 : #define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25)
722 : #define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26)
723 : #define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27)
724 : #define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28)
725 : #define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29)
726 : #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30)
727 : #define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31)
728 :
729 : #define Py_TPFLAGS_DEFAULT ( \
730 : Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
731 : 0)
732 :
733 : /* NOTE: Some of the following flags reuse lower bits (removed as part of the
734 : * Python 3.0 transition). */
735 :
736 : /* The following flags are kept for compatibility; in previous
737 : * versions they indicated presence of newer tp_* fields on the
738 : * type struct.
739 : * Starting with 3.8, binary compatibility of C extensions across
740 : * feature releases of Python is not supported anymore (except when
741 : * using the stable ABI, in which all classes are created dynamically,
742 : * using the interpreter's memory layout.)
743 : * Note that older extensions using the stable ABI set these flags,
744 : * so the bits must not be repurposed.
745 : */
746 : #define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0)
747 : #define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18)
748 :
749 :
750 : /*
751 : The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
752 : reference counts. Py_DECREF calls the object's deallocator function when
753 : the refcount falls to 0; for
754 : objects that don't contain references to other objects or heap memory
755 : this can be the standard function free(). Both macros can be used
756 : wherever a void expression is allowed. The argument must not be a
757 : NULL pointer. If it may be NULL, use Py_XINCREF/Py_XDECREF instead.
758 : The macro _Py_NewReference(op) initialize reference counts to 1, and
759 : in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
760 : bookkeeping appropriate to the special build.
761 :
762 : We assume that the reference count field can never overflow; this can
763 : be proven when the size of the field is the same as the pointer size, so
764 : we ignore the possibility. Provided a C int is at least 32 bits (which
765 : is implicitly assumed in many parts of this code), that's enough for
766 : about 2**31 references to an object.
767 :
768 : XXX The following became out of date in Python 2.2, but I'm not sure
769 : XXX what the full truth is now. Certainly, heap-allocated type objects
770 : XXX can and should be deallocated.
771 : Type objects should never be deallocated; the type pointer in an object
772 : is not considered to be a reference to the type object, to save
773 : complications in the deallocation function. (This is actually a
774 : decision that's up to the implementer of each new type so if you want,
775 : you can count such references to the type object.)
776 : */
777 :
778 : #if defined(Py_REF_DEBUG) && !defined(Py_LIMITED_API)
779 : PyAPI_FUNC(void) _Py_NegativeRefcount(const char *filename, int lineno,
780 : PyObject *op);
781 : PyAPI_FUNC(void) _Py_INCREF_IncRefTotal(void);
782 : PyAPI_FUNC(void) _Py_DECREF_DecRefTotal(void);
783 : #endif // Py_REF_DEBUG && !Py_LIMITED_API
784 :
785 : PyAPI_FUNC(void) _Py_Dealloc(PyObject *);
786 :
787 : /*
788 : These are provided as conveniences to Python runtime embedders, so that
789 : they can have object code that is not dependent on Python compilation flags.
790 : */
791 : PyAPI_FUNC(void) Py_IncRef(PyObject *);
792 : PyAPI_FUNC(void) Py_DecRef(PyObject *);
793 :
794 : // Similar to Py_IncRef() and Py_DecRef() but the argument must be non-NULL.
795 : // Private functions used by Py_INCREF() and Py_DECREF().
796 : PyAPI_FUNC(void) _Py_IncRef(PyObject *);
797 : PyAPI_FUNC(void) _Py_DecRef(PyObject *);
798 :
799 : static inline Py_ALWAYS_INLINE void Py_INCREF(PyObject *op)
800 : {
801 : #if defined(Py_LIMITED_API) && (Py_LIMITED_API+0 >= 0x030c0000 || defined(Py_REF_DEBUG))
802 : // Stable ABI implements Py_INCREF() as a function call on limited C API
803 : // version 3.12 and newer, and on Python built in debug mode. _Py_IncRef()
804 : // was added to Python 3.10.0a7, use Py_IncRef() on older Python versions.
805 : // Py_IncRef() accepts NULL whereas _Py_IncRef() doesn't.
806 : # if Py_LIMITED_API+0 >= 0x030a00A7
807 : _Py_IncRef(op);
808 : # else
809 : Py_IncRef(op);
810 : # endif
811 : #else
812 : // Non-limited C API and limited C API for Python 3.9 and older access
813 : // directly PyObject.ob_refcnt.
814 : #if defined(Py_GIL_DISABLED)
815 : uint32_t local = _Py_atomic_load_uint32_relaxed(&op->ob_ref_local);
816 : uint32_t new_local = local + 1;
817 : if (new_local == 0) {
818 : // local is equal to _Py_IMMORTAL_REFCNT: do nothing
819 : return;
820 : }
821 : if (_Py_IsOwnedByCurrentThread(op)) {
822 : _Py_atomic_store_uint32_relaxed(&op->ob_ref_local, new_local);
823 : }
824 : else {
825 : _Py_atomic_add_ssize(&op->ob_ref_shared, (1 << _Py_REF_SHARED_SHIFT));
826 : }
827 : #elif SIZEOF_VOID_P > 4
828 : // Portable saturated add, branching on the carry flag and set low bits
829 7321 : PY_UINT32_T cur_refcnt = op->ob_refcnt_split[PY_BIG_ENDIAN];
830 7321 : PY_UINT32_T new_refcnt = cur_refcnt + 1;
831 6847 : if (new_refcnt == 0) {
832 : // cur_refcnt is equal to _Py_IMMORTAL_REFCNT: the object is immortal,
833 : // do nothing
834 1133 : return;
835 : }
836 6188 : op->ob_refcnt_split[PY_BIG_ENDIAN] = new_refcnt;
837 : #else
838 : // Explicitly check immortality against the immortal value
839 : if (_Py_IsImmortal(op)) {
840 : return;
841 : }
842 : op->ob_refcnt++;
843 : #endif
844 : _Py_INCREF_STAT_INC();
845 : #ifdef Py_REF_DEBUG
846 : _Py_INCREF_IncRefTotal();
847 : #endif
848 : #endif
849 : }
850 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
851 : # define Py_INCREF(op) Py_INCREF(_PyObject_CAST(op))
852 : #endif
853 :
854 :
855 : #if !defined(Py_LIMITED_API) && defined(Py_GIL_DISABLED)
856 : // Implements Py_DECREF on objects not owned by the current thread.
857 : PyAPI_FUNC(void) _Py_DecRefShared(PyObject *);
858 : PyAPI_FUNC(void) _Py_DecRefSharedDebug(PyObject *, const char *, int);
859 :
860 : // Called from Py_DECREF by the owning thread when the local refcount reaches
861 : // zero. The call will deallocate the object if the shared refcount is also
862 : // zero. Otherwise, the thread gives up ownership and merges the reference
863 : // count fields.
864 : PyAPI_FUNC(void) _Py_MergeZeroLocalRefcount(PyObject *);
865 : #endif
866 :
867 : #if defined(Py_LIMITED_API) && (Py_LIMITED_API+0 >= 0x030c0000 || defined(Py_REF_DEBUG))
868 : // Stable ABI implements Py_DECREF() as a function call on limited C API
869 : // version 3.12 and newer, and on Python built in debug mode. _Py_DecRef() was
870 : // added to Python 3.10.0a7, use Py_DecRef() on older Python versions.
871 : // Py_DecRef() accepts NULL whereas _Py_IncRef() doesn't.
872 : static inline void Py_DECREF(PyObject *op) {
873 : # if Py_LIMITED_API+0 >= 0x030a00A7
874 : _Py_DecRef(op);
875 : # else
876 : Py_DecRef(op);
877 : # endif
878 : }
879 : #define Py_DECREF(op) Py_DECREF(_PyObject_CAST(op))
880 :
881 : #elif defined(Py_GIL_DISABLED) && defined(Py_REF_DEBUG)
882 : static inline void Py_DECREF(const char *filename, int lineno, PyObject *op)
883 : {
884 : uint32_t local = _Py_atomic_load_uint32_relaxed(&op->ob_ref_local);
885 : if (local == _Py_IMMORTAL_REFCNT_LOCAL) {
886 : return;
887 : }
888 : _Py_DECREF_STAT_INC();
889 : _Py_DECREF_DecRefTotal();
890 : if (_Py_IsOwnedByCurrentThread(op)) {
891 : if (local == 0) {
892 : _Py_NegativeRefcount(filename, lineno, op);
893 : }
894 : local--;
895 : _Py_atomic_store_uint32_relaxed(&op->ob_ref_local, local);
896 : if (local == 0) {
897 : _Py_MergeZeroLocalRefcount(op);
898 : }
899 : }
900 : else {
901 : _Py_DecRefSharedDebug(op, filename, lineno);
902 : }
903 : }
904 : #define Py_DECREF(op) Py_DECREF(__FILE__, __LINE__, _PyObject_CAST(op))
905 :
906 : #elif defined(Py_GIL_DISABLED)
907 : static inline void Py_DECREF(PyObject *op)
908 : {
909 : uint32_t local = _Py_atomic_load_uint32_relaxed(&op->ob_ref_local);
910 : if (local == _Py_IMMORTAL_REFCNT_LOCAL) {
911 : return;
912 : }
913 : _Py_DECREF_STAT_INC();
914 : if (_Py_IsOwnedByCurrentThread(op)) {
915 : local--;
916 : _Py_atomic_store_uint32_relaxed(&op->ob_ref_local, local);
917 : if (local == 0) {
918 : _Py_MergeZeroLocalRefcount(op);
919 : }
920 : }
921 : else {
922 : _Py_DecRefShared(op);
923 : }
924 : }
925 : #define Py_DECREF(op) Py_DECREF(_PyObject_CAST(op))
926 :
927 : #elif defined(Py_REF_DEBUG)
928 : static inline void Py_DECREF(const char *filename, int lineno, PyObject *op)
929 : {
930 : if (op->ob_refcnt <= 0) {
931 : _Py_NegativeRefcount(filename, lineno, op);
932 : }
933 : if (_Py_IsImmortal(op)) {
934 : return;
935 : }
936 : _Py_DECREF_STAT_INC();
937 : _Py_DECREF_DecRefTotal();
938 : if (--op->ob_refcnt == 0) {
939 : _Py_Dealloc(op);
940 : }
941 : }
942 : #define Py_DECREF(op) Py_DECREF(__FILE__, __LINE__, _PyObject_CAST(op))
943 :
944 : #else
945 : static inline Py_ALWAYS_INLINE void Py_DECREF(PyObject *op)
946 : {
947 : // Non-limited C API and limited C API for Python 3.9 and older access
948 : // directly PyObject.ob_refcnt.
949 19700 : if (_Py_IsImmortal(op)) {
950 5893 : return;
951 : }
952 : _Py_DECREF_STAT_INC();
953 13807 : if (--op->ob_refcnt == 0) {
954 4497 : _Py_Dealloc(op);
955 : }
956 : }
957 : #define Py_DECREF(op) Py_DECREF(_PyObject_CAST(op))
958 : #endif
959 :
960 :
961 : /* Safely decref `op` and set `op` to NULL, especially useful in tp_clear
962 : * and tp_dealloc implementations.
963 : *
964 : * Note that "the obvious" code can be deadly:
965 : *
966 : * Py_XDECREF(op);
967 : * op = NULL;
968 : *
969 : * Typically, `op` is something like self->containee, and `self` is done
970 : * using its `containee` member. In the code sequence above, suppose
971 : * `containee` is non-NULL with a refcount of 1. Its refcount falls to
972 : * 0 on the first line, which can trigger an arbitrary amount of code,
973 : * possibly including finalizers (like __del__ methods or weakref callbacks)
974 : * coded in Python, which in turn can release the GIL and allow other threads
975 : * to run, etc. Such code may even invoke methods of `self` again, or cause
976 : * cyclic gc to trigger, but-- oops! --self->containee still points to the
977 : * object being torn down, and it may be in an insane state while being torn
978 : * down. This has in fact been a rich historic source of miserable (rare &
979 : * hard-to-diagnose) segfaulting (and other) bugs.
980 : *
981 : * The safe way is:
982 : *
983 : * Py_CLEAR(op);
984 : *
985 : * That arranges to set `op` to NULL _before_ decref'ing, so that any code
986 : * triggered as a side-effect of `op` getting torn down no longer believes
987 : * `op` points to a valid object.
988 : *
989 : * There are cases where it's safe to use the naive code, but they're brittle.
990 : * For example, if `op` points to a Python integer, you know that destroying
991 : * one of those can't cause problems -- but in part that relies on that
992 : * Python integers aren't currently weakly referencable. Best practice is
993 : * to use Py_CLEAR() even if you can't think of a reason for why you need to.
994 : *
995 : * gh-98724: Use a temporary variable to only evaluate the macro argument once,
996 : * to avoid the duplication of side effects if the argument has side effects.
997 : *
998 : * gh-99701: If the PyObject* type is used with casting arguments to PyObject*,
999 : * the code can be miscompiled with strict aliasing because of type punning.
1000 : * With strict aliasing, a compiler considers that two pointers of different
1001 : * types cannot read or write the same memory which enables optimization
1002 : * opportunities.
1003 : *
1004 : * If available, use _Py_TYPEOF() to use the 'op' type for temporary variables,
1005 : * and so avoid type punning. Otherwise, use memcpy() which causes type erasure
1006 : * and so prevents the compiler to reuse an old cached 'op' value after
1007 : * Py_CLEAR().
1008 : */
1009 : #ifdef _Py_TYPEOF
1010 : #define Py_CLEAR(op) \
1011 : do { \
1012 : _Py_TYPEOF(op)* _tmp_op_ptr = &(op); \
1013 : _Py_TYPEOF(op) _tmp_old_op = (*_tmp_op_ptr); \
1014 : if (_tmp_old_op != NULL) { \
1015 : *_tmp_op_ptr = _Py_NULL; \
1016 : Py_DECREF(_tmp_old_op); \
1017 : } \
1018 : } while (0)
1019 : #else
1020 : #define Py_CLEAR(op) \
1021 : do { \
1022 : PyObject **_tmp_op_ptr = _Py_CAST(PyObject**, &(op)); \
1023 : PyObject *_tmp_old_op = (*_tmp_op_ptr); \
1024 : if (_tmp_old_op != NULL) { \
1025 : PyObject *_null_ptr = _Py_NULL; \
1026 : memcpy(_tmp_op_ptr, &_null_ptr, sizeof(PyObject*)); \
1027 : Py_DECREF(_tmp_old_op); \
1028 : } \
1029 : } while (0)
1030 : #endif
1031 :
1032 :
1033 : /* Function to use in case the object pointer can be NULL: */
1034 377 : static inline void Py_XINCREF(PyObject *op)
1035 : {
1036 377 : if (op != _Py_NULL) {
1037 : Py_INCREF(op);
1038 : }
1039 377 : }
1040 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
1041 : # define Py_XINCREF(op) Py_XINCREF(_PyObject_CAST(op))
1042 : #endif
1043 :
1044 8393 : static inline void Py_XDECREF(PyObject *op)
1045 : {
1046 8393 : if (op != _Py_NULL) {
1047 : Py_DECREF(op);
1048 : }
1049 8393 : }
1050 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
1051 : # define Py_XDECREF(op) Py_XDECREF(_PyObject_CAST(op))
1052 : #endif
1053 :
1054 : // Create a new strong reference to an object:
1055 : // increment the reference count of the object and return the object.
1056 : PyAPI_FUNC(PyObject*) Py_NewRef(PyObject *obj);
1057 :
1058 : // Similar to Py_NewRef(), but the object can be NULL.
1059 : PyAPI_FUNC(PyObject*) Py_XNewRef(PyObject *obj);
1060 :
1061 525 : static inline PyObject* _Py_NewRef(PyObject *obj)
1062 : {
1063 : Py_INCREF(obj);
1064 525 : return obj;
1065 : }
1066 :
1067 : static inline PyObject* _Py_XNewRef(PyObject *obj)
1068 : {
1069 : Py_XINCREF(obj);
1070 : return obj;
1071 : }
1072 :
1073 : // Py_NewRef() and Py_XNewRef() are exported as functions for the stable ABI.
1074 : // Names overridden with macros by static inline functions for best
1075 : // performances.
1076 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
1077 : # define Py_NewRef(obj) _Py_NewRef(_PyObject_CAST(obj))
1078 : # define Py_XNewRef(obj) _Py_XNewRef(_PyObject_CAST(obj))
1079 : #else
1080 : # define Py_NewRef(obj) _Py_NewRef(obj)
1081 : # define Py_XNewRef(obj) _Py_XNewRef(obj)
1082 : #endif
1083 :
1084 :
1085 : #define Py_CONSTANT_NONE 0
1086 : #define Py_CONSTANT_FALSE 1
1087 : #define Py_CONSTANT_TRUE 2
1088 : #define Py_CONSTANT_ELLIPSIS 3
1089 : #define Py_CONSTANT_NOT_IMPLEMENTED 4
1090 : #define Py_CONSTANT_ZERO 5
1091 : #define Py_CONSTANT_ONE 6
1092 : #define Py_CONSTANT_EMPTY_STR 7
1093 : #define Py_CONSTANT_EMPTY_BYTES 8
1094 : #define Py_CONSTANT_EMPTY_TUPLE 9
1095 :
1096 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
1097 : PyAPI_FUNC(PyObject*) Py_GetConstant(unsigned int constant_id);
1098 : PyAPI_FUNC(PyObject*) Py_GetConstantBorrowed(unsigned int constant_id);
1099 : #endif
1100 :
1101 :
1102 : /*
1103 : _Py_NoneStruct is an object of undefined type which can be used in contexts
1104 : where NULL (nil) is not suitable (since NULL often means 'error').
1105 : */
1106 : PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
1107 :
1108 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030D0000
1109 : # define Py_None Py_GetConstantBorrowed(Py_CONSTANT_NONE)
1110 : #else
1111 : # define Py_None (&_Py_NoneStruct)
1112 : #endif
1113 :
1114 : // Test if an object is the None singleton, the same as "x is None" in Python.
1115 : PyAPI_FUNC(int) Py_IsNone(PyObject *x);
1116 : #define Py_IsNone(x) Py_Is((x), Py_None)
1117 :
1118 : /* Macro for returning Py_None from a function.
1119 : * Only treat Py_None as immortal in the limited C API 3.12 and newer. */
1120 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 < 0x030c0000
1121 : # define Py_RETURN_NONE return Py_NewRef(Py_None)
1122 : #else
1123 : # define Py_RETURN_NONE return Py_None
1124 : #endif
1125 :
1126 : /*
1127 : Py_NotImplemented is a singleton used to signal that an operation is
1128 : not implemented for a given type combination.
1129 : */
1130 : PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
1131 :
1132 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030D0000
1133 : # define Py_NotImplemented Py_GetConstantBorrowed(Py_CONSTANT_NOT_IMPLEMENTED)
1134 : #else
1135 : # define Py_NotImplemented (&_Py_NotImplementedStruct)
1136 : #endif
1137 :
1138 : /* Macro for returning Py_NotImplemented from a function */
1139 : #define Py_RETURN_NOTIMPLEMENTED return Py_NotImplemented
1140 :
1141 : /* Rich comparison opcodes */
1142 : #define Py_LT 0
1143 : #define Py_LE 1
1144 : #define Py_EQ 2
1145 : #define Py_NE 3
1146 : #define Py_GT 4
1147 : #define Py_GE 5
1148 :
1149 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000
1150 : /* Result of calling PyIter_Send */
1151 : typedef enum {
1152 : PYGEN_RETURN = 0,
1153 : PYGEN_ERROR = -1,
1154 : PYGEN_NEXT = 1,
1155 : } PySendResult;
1156 : #endif
1157 :
1158 : /*
1159 : * Macro for implementing rich comparisons
1160 : *
1161 : * Needs to be a macro because any C-comparable type can be used.
1162 : */
1163 : #define Py_RETURN_RICHCOMPARE(val1, val2, op) \
1164 : do { \
1165 : switch (op) { \
1166 : case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
1167 : case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
1168 : case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
1169 : case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
1170 : case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
1171 : case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
1172 : default: \
1173 : Py_UNREACHABLE(); \
1174 : } \
1175 : } while (0)
1176 :
1177 :
1178 : /*
1179 : More conventions
1180 : ================
1181 :
1182 : Argument Checking
1183 : -----------------
1184 :
1185 : Functions that take objects as arguments normally don't check for nil
1186 : arguments, but they do check the type of the argument, and return an
1187 : error if the function doesn't apply to the type.
1188 :
1189 : Failure Modes
1190 : -------------
1191 :
1192 : Functions may fail for a variety of reasons, including running out of
1193 : memory. This is communicated to the caller in two ways: an error string
1194 : is set (see errors.h), and the function result differs: functions that
1195 : normally return a pointer return NULL for failure, functions returning
1196 : an integer return -1 (which could be a legal return value too!), and
1197 : other functions return 0 for success and -1 for failure.
1198 : Callers should always check for errors before using the result. If
1199 : an error was set, the caller must either explicitly clear it, or pass
1200 : the error on to its caller.
1201 :
1202 : Reference Counts
1203 : ----------------
1204 :
1205 : It takes a while to get used to the proper usage of reference counts.
1206 :
1207 : Functions that create an object set the reference count to 1; such new
1208 : objects must be stored somewhere or destroyed again with Py_DECREF().
1209 : Some functions that 'store' objects, such as PyTuple_SetItem() and
1210 : PyList_SetItem(),
1211 : don't increment the reference count of the object, since the most
1212 : frequent use is to store a fresh object. Functions that 'retrieve'
1213 : objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
1214 : don't increment
1215 : the reference count, since most frequently the object is only looked at
1216 : quickly. Thus, to retrieve an object and store it again, the caller
1217 : must call Py_INCREF() explicitly.
1218 :
1219 : NOTE: functions that 'consume' a reference count, like
1220 : PyList_SetItem(), consume the reference even if the object wasn't
1221 : successfully stored, to simplify error handling.
1222 :
1223 : It seems attractive to make other functions that take an object as
1224 : argument consume a reference count; however, this may quickly get
1225 : confusing (even the current practice is already confusing). Consider
1226 : it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
1227 : times.
1228 : */
1229 :
1230 : #ifndef Py_LIMITED_API
1231 : # define Py_CPYTHON_OBJECT_H
1232 : # include "cpython/object.h"
1233 : # undef Py_CPYTHON_OBJECT_H
1234 : #endif
1235 :
1236 :
1237 : static inline int
1238 3166 : PyType_HasFeature(PyTypeObject *type, unsigned long feature)
1239 : {
1240 : unsigned long flags;
1241 : #ifdef Py_LIMITED_API
1242 : // PyTypeObject is opaque in the limited C API
1243 3166 : flags = PyType_GetFlags(type);
1244 : #else
1245 : # ifdef Py_GIL_DISABLED
1246 : flags = _Py_atomic_load_ulong_relaxed(&type->tp_flags);
1247 : # else
1248 : flags = type->tp_flags;
1249 : # endif
1250 : #endif
1251 3166 : return ((flags & feature) != 0);
1252 : }
1253 :
1254 : #define PyType_FastSubclass(type, flag) PyType_HasFeature((type), (flag))
1255 :
1256 : static inline int PyType_Check(PyObject *op) {
1257 : return PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS);
1258 : }
1259 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
1260 : # define PyType_Check(op) PyType_Check(_PyObject_CAST(op))
1261 : #endif
1262 :
1263 : #define _PyType_CAST(op) \
1264 : (assert(PyType_Check(op)), _Py_CAST(PyTypeObject*, (op)))
1265 :
1266 : static inline int PyType_CheckExact(PyObject *op) {
1267 : return Py_IS_TYPE(op, &PyType_Type);
1268 : }
1269 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
1270 : # define PyType_CheckExact(op) PyType_CheckExact(_PyObject_CAST(op))
1271 : #endif
1272 :
1273 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
1274 : PyAPI_FUNC(PyObject *) PyType_GetModuleByDef(PyTypeObject *, PyModuleDef *);
1275 : #endif
1276 :
1277 : #ifdef __cplusplus
1278 : }
1279 : #endif
1280 : #endif // !Py_OBJECT_H
|
