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 : // Kept for backward compatibility. It was needed by Py_TRACE_REFS build.
63 : #define _PyObject_EXTRA_INIT
64 :
65 : /* Make all uses of PyObject_HEAD_INIT immortal.
66 : *
67 : * Statically allocated objects might be shared between
68 : * interpreters, so must be marked as immortal.
69 : */
70 : #if defined(Py_GIL_DISABLED)
71 : #define PyObject_HEAD_INIT(type) \
72 : { \
73 : 0, \
74 : _Py_STATICALLY_ALLOCATED_FLAG, \
75 : { 0 }, \
76 : 0, \
77 : _Py_IMMORTAL_REFCNT_LOCAL, \
78 : 0, \
79 : (type), \
80 : },
81 : #else
82 : #define PyObject_HEAD_INIT(type) \
83 : { \
84 : { _Py_STATIC_IMMORTAL_INITIAL_REFCNT }, \
85 : (type) \
86 : },
87 : #endif
88 :
89 : #define PyVarObject_HEAD_INIT(type, size) \
90 : { \
91 : PyObject_HEAD_INIT(type) \
92 : (size) \
93 : },
94 :
95 : /* PyObject_VAR_HEAD defines the initial segment of all variable-size
96 : * container objects. These end with a declaration of an array with 1
97 : * element, but enough space is malloc'ed so that the array actually
98 : * has room for ob_size elements. Note that ob_size is an element count,
99 : * not necessarily a byte count.
100 : */
101 : #define PyObject_VAR_HEAD PyVarObject ob_base;
102 : #define Py_INVALID_SIZE (Py_ssize_t)-1
103 :
104 : /* Nothing is actually declared to be a PyObject, but every pointer to
105 : * a Python object can be cast to a PyObject*. This is inheritance built
106 : * by hand. Similarly every pointer to a variable-size Python object can,
107 : * in addition, be cast to PyVarObject*.
108 : */
109 : #ifndef Py_GIL_DISABLED
110 : struct _object {
111 : #if (defined(__GNUC__) || defined(__clang__)) \
112 : && !(defined __STDC_VERSION__ && __STDC_VERSION__ >= 201112L)
113 : // On C99 and older, anonymous union is a GCC and clang extension
114 : __extension__
115 : #endif
116 : #ifdef _MSC_VER
117 : // Ignore MSC warning C4201: "nonstandard extension used:
118 : // nameless struct/union"
119 : __pragma(warning(push))
120 : __pragma(warning(disable: 4201))
121 : #endif
122 : union {
123 : #if SIZEOF_VOID_P > 4
124 : PY_INT64_T ob_refcnt_full; /* This field is needed for efficient initialization with Clang on ARM */
125 : struct {
126 : # if PY_BIG_ENDIAN
127 : uint16_t ob_flags;
128 : uint16_t ob_overflow;
129 : uint32_t ob_refcnt;
130 : # else
131 : uint32_t ob_refcnt;
132 : uint16_t ob_overflow;
133 : uint16_t ob_flags;
134 : # endif
135 : };
136 : #else
137 : Py_ssize_t ob_refcnt;
138 : #endif
139 : };
140 : #ifdef _MSC_VER
141 : __pragma(warning(pop))
142 : #endif
143 :
144 : PyTypeObject *ob_type;
145 : };
146 : #else
147 : // Objects that are not owned by any thread use a thread id (tid) of zero.
148 : // This includes both immortal objects and objects whose reference count
149 : // fields have been merged.
150 : #define _Py_UNOWNED_TID 0
151 :
152 : struct _object {
153 : // ob_tid stores the thread id (or zero). It is also used by the GC and the
154 : // trashcan mechanism as a linked list pointer and by the GC to store the
155 : // computed "gc_refs" refcount.
156 : uintptr_t ob_tid;
157 : uint16_t ob_flags;
158 : PyMutex ob_mutex; // per-object lock
159 : uint8_t ob_gc_bits; // gc-related state
160 : uint32_t ob_ref_local; // local reference count
161 : Py_ssize_t ob_ref_shared; // shared (atomic) reference count
162 : PyTypeObject *ob_type;
163 : };
164 : #endif
165 :
166 : /* Cast argument to PyObject* type. */
167 : #define _PyObject_CAST(op) _Py_CAST(PyObject*, (op))
168 :
169 : typedef struct {
170 : PyObject ob_base;
171 : Py_ssize_t ob_size; /* Number of items in variable part */
172 : } PyVarObject;
173 :
174 : /* Cast argument to PyVarObject* type. */
175 : #define _PyVarObject_CAST(op) _Py_CAST(PyVarObject*, (op))
176 :
177 :
178 : // Test if the 'x' object is the 'y' object, the same as "x is y" in Python.
179 : PyAPI_FUNC(int) Py_Is(PyObject *x, PyObject *y);
180 : #define Py_Is(x, y) ((x) == (y))
181 :
182 : #if defined(Py_GIL_DISABLED) && !defined(Py_LIMITED_API)
183 : PyAPI_FUNC(uintptr_t) _Py_GetThreadLocal_Addr(void);
184 :
185 : static inline uintptr_t
186 : _Py_ThreadId(void)
187 : {
188 : uintptr_t tid;
189 : #if defined(_MSC_VER) && defined(_M_X64)
190 : tid = __readgsqword(48);
191 : #elif defined(_MSC_VER) && defined(_M_IX86)
192 : tid = __readfsdword(24);
193 : #elif defined(_MSC_VER) && defined(_M_ARM64)
194 : tid = __getReg(18);
195 : #elif defined(__MINGW32__) && defined(_M_X64)
196 : tid = __readgsqword(48);
197 : #elif defined(__MINGW32__) && defined(_M_IX86)
198 : tid = __readfsdword(24);
199 : #elif defined(__MINGW32__) && defined(_M_ARM64)
200 : tid = __getReg(18);
201 : #elif defined(__i386__)
202 : __asm__("movl %%gs:0, %0" : "=r" (tid)); // 32-bit always uses GS
203 : #elif defined(__MACH__) && defined(__x86_64__)
204 : __asm__("movq %%gs:0, %0" : "=r" (tid)); // x86_64 macOSX uses GS
205 : #elif defined(__x86_64__)
206 : __asm__("movq %%fs:0, %0" : "=r" (tid)); // x86_64 Linux, BSD uses FS
207 : #elif defined(__arm__) && __ARM_ARCH >= 7
208 : __asm__ ("mrc p15, 0, %0, c13, c0, 3\nbic %0, %0, #3" : "=r" (tid));
209 : #elif defined(__aarch64__) && defined(__APPLE__)
210 : __asm__ ("mrs %0, tpidrro_el0" : "=r" (tid));
211 : #elif defined(__aarch64__)
212 : __asm__ ("mrs %0, tpidr_el0" : "=r" (tid));
213 : #elif defined(__powerpc64__)
214 : #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer)
215 : tid = (uintptr_t)__builtin_thread_pointer();
216 : #else
217 : // r13 is reserved for use as system thread ID by the Power 64-bit ABI.
218 : register uintptr_t tp __asm__ ("r13");
219 : __asm__("" : "=r" (tp));
220 : tid = tp;
221 : #endif
222 : #elif defined(__powerpc__)
223 : #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer)
224 : tid = (uintptr_t)__builtin_thread_pointer();
225 : #else
226 : // r2 is reserved for use as system thread ID by the Power 32-bit ABI.
227 : register uintptr_t tp __asm__ ("r2");
228 : __asm__ ("" : "=r" (tp));
229 : tid = tp;
230 : #endif
231 : #elif defined(__s390__) && defined(__GNUC__)
232 : // Both GCC and Clang have supported __builtin_thread_pointer
233 : // for s390 from long time ago.
234 : tid = (uintptr_t)__builtin_thread_pointer();
235 : #elif defined(__riscv)
236 : #if defined(__clang__) && _Py__has_builtin(__builtin_thread_pointer)
237 : tid = (uintptr_t)__builtin_thread_pointer();
238 : #else
239 : // tp is Thread Pointer provided by the RISC-V ABI.
240 : __asm__ ("mv %0, tp" : "=r" (tid));
241 : #endif
242 : #else
243 : // Fallback to a portable implementation if we do not have a faster
244 : // platform-specific implementation.
245 : tid = _Py_GetThreadLocal_Addr();
246 : #endif
247 : return tid;
248 : }
249 :
250 : static inline Py_ALWAYS_INLINE int
251 : _Py_IsOwnedByCurrentThread(PyObject *ob)
252 : {
253 : #ifdef _Py_THREAD_SANITIZER
254 : return _Py_atomic_load_uintptr_relaxed(&ob->ob_tid) == _Py_ThreadId();
255 : #else
256 : return ob->ob_tid == _Py_ThreadId();
257 : #endif
258 : }
259 : #endif
260 :
261 : // Py_TYPE() implementation for the stable ABI
262 : PyAPI_FUNC(PyTypeObject*) Py_TYPE(PyObject *ob);
263 :
264 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030e0000
265 : // Stable ABI implements Py_TYPE() as a function call
266 : // on limited C API version 3.14 and newer.
267 : #else
268 68 : static inline PyTypeObject* _Py_TYPE(PyObject *ob)
269 : {
270 68 : return ob->ob_type;
271 : }
272 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
273 : # define Py_TYPE(ob) _Py_TYPE(_PyObject_CAST(ob))
274 : #else
275 : # define Py_TYPE(ob) _Py_TYPE(ob)
276 : #endif
277 : #endif
278 :
279 : PyAPI_DATA(PyTypeObject) PyLong_Type;
280 : PyAPI_DATA(PyTypeObject) PyBool_Type;
281 :
282 : // bpo-39573: The Py_SET_SIZE() function must be used to set an object size.
283 : static inline Py_ssize_t Py_SIZE(PyObject *ob) {
284 : assert(Py_TYPE(ob) != &PyLong_Type);
285 : assert(Py_TYPE(ob) != &PyBool_Type);
286 : return _PyVarObject_CAST(ob)->ob_size;
287 : }
288 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
289 : # define Py_SIZE(ob) Py_SIZE(_PyObject_CAST(ob))
290 : #endif
291 :
292 : static inline int Py_IS_TYPE(PyObject *ob, PyTypeObject *type) {
293 : return Py_TYPE(ob) == type;
294 : }
295 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
296 : # define Py_IS_TYPE(ob, type) Py_IS_TYPE(_PyObject_CAST(ob), (type))
297 : #endif
298 :
299 :
300 : static inline void Py_SET_TYPE(PyObject *ob, PyTypeObject *type) {
301 : ob->ob_type = type;
302 : }
303 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
304 : # define Py_SET_TYPE(ob, type) Py_SET_TYPE(_PyObject_CAST(ob), type)
305 : #endif
306 :
307 : static inline void Py_SET_SIZE(PyVarObject *ob, Py_ssize_t size) {
308 : assert(Py_TYPE(_PyObject_CAST(ob)) != &PyLong_Type);
309 : assert(Py_TYPE(_PyObject_CAST(ob)) != &PyBool_Type);
310 : #ifdef Py_GIL_DISABLED
311 : _Py_atomic_store_ssize_relaxed(&ob->ob_size, size);
312 : #else
313 : ob->ob_size = size;
314 : #endif
315 : }
316 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
317 : # define Py_SET_SIZE(ob, size) Py_SET_SIZE(_PyVarObject_CAST(ob), (size))
318 : #endif
319 :
320 :
321 : /*
322 : Type objects contain a string containing the type name (to help somewhat
323 : in debugging), the allocation parameters (see PyObject_New() and
324 : PyObject_NewVar()),
325 : and methods for accessing objects of the type. Methods are optional, a
326 : nil pointer meaning that particular kind of access is not available for
327 : this type. The Py_DECREF() macro uses the tp_dealloc method without
328 : checking for a nil pointer; it should always be implemented except if
329 : the implementation can guarantee that the reference count will never
330 : reach zero (e.g., for statically allocated type objects).
331 :
332 : NB: the methods for certain type groups are now contained in separate
333 : method blocks.
334 : */
335 :
336 : typedef PyObject * (*unaryfunc)(PyObject *);
337 : typedef PyObject * (*binaryfunc)(PyObject *, PyObject *);
338 : typedef PyObject * (*ternaryfunc)(PyObject *, PyObject *, PyObject *);
339 : typedef int (*inquiry)(PyObject *);
340 : typedef Py_ssize_t (*lenfunc)(PyObject *);
341 : typedef PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t);
342 : typedef PyObject *(*ssizessizeargfunc)(PyObject *, Py_ssize_t, Py_ssize_t);
343 : typedef int(*ssizeobjargproc)(PyObject *, Py_ssize_t, PyObject *);
344 : typedef int(*ssizessizeobjargproc)(PyObject *, Py_ssize_t, Py_ssize_t, PyObject *);
345 : typedef int(*objobjargproc)(PyObject *, PyObject *, PyObject *);
346 :
347 : typedef int (*objobjproc)(PyObject *, PyObject *);
348 : typedef int (*visitproc)(PyObject *, void *);
349 : typedef int (*traverseproc)(PyObject *, visitproc, void *);
350 :
351 :
352 : typedef void (*freefunc)(void *);
353 : typedef void (*destructor)(PyObject *);
354 : typedef PyObject *(*getattrfunc)(PyObject *, char *);
355 : typedef PyObject *(*getattrofunc)(PyObject *, PyObject *);
356 : typedef int (*setattrfunc)(PyObject *, char *, PyObject *);
357 : typedef int (*setattrofunc)(PyObject *, PyObject *, PyObject *);
358 : typedef PyObject *(*reprfunc)(PyObject *);
359 : typedef Py_hash_t (*hashfunc)(PyObject *);
360 : typedef PyObject *(*richcmpfunc) (PyObject *, PyObject *, int);
361 : typedef PyObject *(*getiterfunc) (PyObject *);
362 : typedef PyObject *(*iternextfunc) (PyObject *);
363 : typedef PyObject *(*descrgetfunc) (PyObject *, PyObject *, PyObject *);
364 : typedef int (*descrsetfunc) (PyObject *, PyObject *, PyObject *);
365 : typedef int (*initproc)(PyObject *, PyObject *, PyObject *);
366 : typedef PyObject *(*newfunc)(PyTypeObject *, PyObject *, PyObject *);
367 : typedef PyObject *(*allocfunc)(PyTypeObject *, Py_ssize_t);
368 :
369 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030c0000 // 3.12
370 : typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args,
371 : size_t nargsf, PyObject *kwnames);
372 : #endif
373 :
374 : typedef struct{
375 : int slot; /* slot id, see below */
376 : void *pfunc; /* function pointer */
377 : } PyType_Slot;
378 :
379 : typedef struct{
380 : const char* name;
381 : int basicsize;
382 : int itemsize;
383 : unsigned int flags;
384 : PyType_Slot *slots; /* terminated by slot==0. */
385 : } PyType_Spec;
386 :
387 : PyAPI_FUNC(PyObject*) PyType_FromSpec(PyType_Spec*);
388 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
389 : PyAPI_FUNC(PyObject*) PyType_FromSpecWithBases(PyType_Spec*, PyObject*);
390 : #endif
391 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000
392 : PyAPI_FUNC(void*) PyType_GetSlot(PyTypeObject*, int);
393 : #endif
394 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000
395 : PyAPI_FUNC(PyObject*) PyType_FromModuleAndSpec(PyObject *, PyType_Spec *, PyObject *);
396 : PyAPI_FUNC(PyObject *) PyType_GetModule(PyTypeObject *);
397 : PyAPI_FUNC(void *) PyType_GetModuleState(PyTypeObject *);
398 : #endif
399 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030B0000
400 : PyAPI_FUNC(PyObject *) PyType_GetName(PyTypeObject *);
401 : PyAPI_FUNC(PyObject *) PyType_GetQualName(PyTypeObject *);
402 : #endif
403 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030D0000
404 : PyAPI_FUNC(PyObject *) PyType_GetFullyQualifiedName(PyTypeObject *type);
405 : PyAPI_FUNC(PyObject *) PyType_GetModuleName(PyTypeObject *type);
406 : #endif
407 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
408 : PyAPI_FUNC(PyObject *) PyType_FromMetaclass(PyTypeObject*, PyObject*, PyType_Spec*, PyObject*);
409 : PyAPI_FUNC(void *) PyObject_GetTypeData(PyObject *obj, PyTypeObject *cls);
410 : PyAPI_FUNC(Py_ssize_t) PyType_GetTypeDataSize(PyTypeObject *cls);
411 : #endif
412 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030E0000
413 : PyAPI_FUNC(int) PyType_GetBaseByToken(PyTypeObject *, void *, PyTypeObject **);
414 : #define Py_TP_USE_SPEC NULL
415 : #endif
416 :
417 : /* Generic type check */
418 : PyAPI_FUNC(int) PyType_IsSubtype(PyTypeObject *, PyTypeObject *);
419 :
420 : static inline int PyObject_TypeCheck(PyObject *ob, PyTypeObject *type) {
421 : return Py_IS_TYPE(ob, type) || PyType_IsSubtype(Py_TYPE(ob), type);
422 : }
423 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
424 : # define PyObject_TypeCheck(ob, type) PyObject_TypeCheck(_PyObject_CAST(ob), (type))
425 : #endif
426 :
427 : PyAPI_DATA(PyTypeObject) PyType_Type; /* built-in 'type' */
428 : PyAPI_DATA(PyTypeObject) PyBaseObject_Type; /* built-in 'object' */
429 : PyAPI_DATA(PyTypeObject) PySuper_Type; /* built-in 'super' */
430 :
431 : PyAPI_FUNC(unsigned long) PyType_GetFlags(PyTypeObject*);
432 :
433 : PyAPI_FUNC(int) PyType_Ready(PyTypeObject *);
434 : PyAPI_FUNC(PyObject *) PyType_GenericAlloc(PyTypeObject *, Py_ssize_t);
435 : PyAPI_FUNC(PyObject *) PyType_GenericNew(PyTypeObject *,
436 : PyObject *, PyObject *);
437 : PyAPI_FUNC(unsigned int) PyType_ClearCache(void);
438 : PyAPI_FUNC(void) PyType_Modified(PyTypeObject *);
439 :
440 : /* Generic operations on objects */
441 : PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
442 : PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
443 : PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *);
444 : PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *);
445 : PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
446 : PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);
447 : PyAPI_FUNC(PyObject *) PyObject_GetAttrString(PyObject *, const char *);
448 : PyAPI_FUNC(int) PyObject_SetAttrString(PyObject *, const char *, PyObject *);
449 : PyAPI_FUNC(int) PyObject_DelAttrString(PyObject *v, const char *name);
450 : PyAPI_FUNC(int) PyObject_HasAttrString(PyObject *, const char *);
451 : PyAPI_FUNC(PyObject *) PyObject_GetAttr(PyObject *, PyObject *);
452 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
453 : PyAPI_FUNC(int) PyObject_GetOptionalAttr(PyObject *, PyObject *, PyObject **);
454 : PyAPI_FUNC(int) PyObject_GetOptionalAttrString(PyObject *, const char *, PyObject **);
455 : #endif
456 : PyAPI_FUNC(int) PyObject_SetAttr(PyObject *, PyObject *, PyObject *);
457 : PyAPI_FUNC(int) PyObject_DelAttr(PyObject *v, PyObject *name);
458 : PyAPI_FUNC(int) PyObject_HasAttr(PyObject *, PyObject *);
459 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
460 : PyAPI_FUNC(int) PyObject_HasAttrWithError(PyObject *, PyObject *);
461 : PyAPI_FUNC(int) PyObject_HasAttrStringWithError(PyObject *, const char *);
462 : #endif
463 : PyAPI_FUNC(PyObject *) PyObject_SelfIter(PyObject *);
464 : PyAPI_FUNC(PyObject *) PyObject_GenericGetAttr(PyObject *, PyObject *);
465 : PyAPI_FUNC(int) PyObject_GenericSetAttr(PyObject *, PyObject *, PyObject *);
466 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
467 : PyAPI_FUNC(int) PyObject_GenericSetDict(PyObject *, PyObject *, void *);
468 : #endif
469 : PyAPI_FUNC(Py_hash_t) PyObject_Hash(PyObject *);
470 : PyAPI_FUNC(Py_hash_t) PyObject_HashNotImplemented(PyObject *);
471 : PyAPI_FUNC(int) PyObject_IsTrue(PyObject *);
472 : PyAPI_FUNC(int) PyObject_Not(PyObject *);
473 : PyAPI_FUNC(int) PyCallable_Check(PyObject *);
474 : PyAPI_FUNC(void) PyObject_ClearWeakRefs(PyObject *);
475 :
476 : /* PyObject_Dir(obj) acts like Python builtins.dir(obj), returning a
477 : list of strings. PyObject_Dir(NULL) is like builtins.dir(),
478 : returning the names of the current locals. In this case, if there are
479 : no current locals, NULL is returned, and PyErr_Occurred() is false.
480 : */
481 : PyAPI_FUNC(PyObject *) PyObject_Dir(PyObject *);
482 :
483 : /* Helpers for printing recursive container types */
484 : PyAPI_FUNC(int) Py_ReprEnter(PyObject *);
485 : PyAPI_FUNC(void) Py_ReprLeave(PyObject *);
486 :
487 : /* Flag bits for printing: */
488 : #define Py_PRINT_RAW 1 /* No string quotes etc. */
489 :
490 : /*
491 : Type flags (tp_flags)
492 :
493 : These flags are used to change expected features and behavior for a
494 : particular type.
495 :
496 : Arbitration of the flag bit positions will need to be coordinated among
497 : all extension writers who publicly release their extensions (this will
498 : be fewer than you might expect!).
499 :
500 : Most flags were removed as of Python 3.0 to make room for new flags. (Some
501 : flags are not for backwards compatibility but to indicate the presence of an
502 : optional feature; these flags remain of course.)
503 :
504 : Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
505 :
506 : Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
507 : given type object has a specified feature.
508 : */
509 :
510 : #ifndef Py_LIMITED_API
511 :
512 : /* Track types initialized using _PyStaticType_InitBuiltin(). */
513 : #define _Py_TPFLAGS_STATIC_BUILTIN (1 << 1)
514 :
515 : /* The values array is placed inline directly after the rest of
516 : * the object. Implies Py_TPFLAGS_HAVE_GC.
517 : */
518 : #define Py_TPFLAGS_INLINE_VALUES (1 << 2)
519 :
520 : /* Placement of weakref pointers are managed by the VM, not by the type.
521 : * The VM will automatically set tp_weaklistoffset.
522 : */
523 : #define Py_TPFLAGS_MANAGED_WEAKREF (1 << 3)
524 :
525 : /* Placement of dict (and values) pointers are managed by the VM, not by the type.
526 : * The VM will automatically set tp_dictoffset. Implies Py_TPFLAGS_HAVE_GC.
527 : */
528 : #define Py_TPFLAGS_MANAGED_DICT (1 << 4)
529 :
530 : #define Py_TPFLAGS_PREHEADER (Py_TPFLAGS_MANAGED_WEAKREF | Py_TPFLAGS_MANAGED_DICT)
531 :
532 : /* Set if instances of the type object are treated as sequences for pattern matching */
533 : #define Py_TPFLAGS_SEQUENCE (1 << 5)
534 : /* Set if instances of the type object are treated as mappings for pattern matching */
535 : #define Py_TPFLAGS_MAPPING (1 << 6)
536 : #endif
537 :
538 : /* Disallow creating instances of the type: set tp_new to NULL and don't create
539 : * the "__new__" key in the type dictionary. */
540 : #define Py_TPFLAGS_DISALLOW_INSTANTIATION (1UL << 7)
541 :
542 : /* Set if the type object is immutable: type attributes cannot be set nor deleted */
543 : #define Py_TPFLAGS_IMMUTABLETYPE (1UL << 8)
544 :
545 : /* Set if the type object is dynamically allocated */
546 : #define Py_TPFLAGS_HEAPTYPE (1UL << 9)
547 :
548 : /* Set if the type allows subclassing */
549 : #define Py_TPFLAGS_BASETYPE (1UL << 10)
550 :
551 : /* Set if the type implements the vectorcall protocol (PEP 590) */
552 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030C0000
553 : #define Py_TPFLAGS_HAVE_VECTORCALL (1UL << 11)
554 : #ifndef Py_LIMITED_API
555 : // Backwards compatibility alias for API that was provisional in Python 3.8
556 : #define _Py_TPFLAGS_HAVE_VECTORCALL Py_TPFLAGS_HAVE_VECTORCALL
557 : #endif
558 : #endif
559 :
560 : /* Set if the type is 'ready' -- fully initialized */
561 : #define Py_TPFLAGS_READY (1UL << 12)
562 :
563 : /* Set while the type is being 'readied', to prevent recursive ready calls */
564 : #define Py_TPFLAGS_READYING (1UL << 13)
565 :
566 : /* Objects support garbage collection (see objimpl.h) */
567 : #define Py_TPFLAGS_HAVE_GC (1UL << 14)
568 :
569 : /* These two bits are preserved for Stackless Python, next after this is 17 */
570 : #ifdef STACKLESS
571 : #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (3UL << 15)
572 : #else
573 : #define Py_TPFLAGS_HAVE_STACKLESS_EXTENSION 0
574 : #endif
575 :
576 : /* Objects behave like an unbound method */
577 : #define Py_TPFLAGS_METHOD_DESCRIPTOR (1UL << 17)
578 :
579 : /* Unused. Legacy flag */
580 : #define Py_TPFLAGS_VALID_VERSION_TAG (1UL << 19)
581 :
582 : /* Type is abstract and cannot be instantiated */
583 : #define Py_TPFLAGS_IS_ABSTRACT (1UL << 20)
584 :
585 : // This undocumented flag gives certain built-ins their unique pattern-matching
586 : // behavior, which allows a single positional subpattern to match against the
587 : // subject itself (rather than a mapped attribute on it):
588 : #define _Py_TPFLAGS_MATCH_SELF (1UL << 22)
589 :
590 : /* Items (ob_size*tp_itemsize) are found at the end of an instance's memory */
591 : #define Py_TPFLAGS_ITEMS_AT_END (1UL << 23)
592 :
593 : /* These flags are used to determine if a type is a subclass. */
594 : #define Py_TPFLAGS_LONG_SUBCLASS (1UL << 24)
595 : #define Py_TPFLAGS_LIST_SUBCLASS (1UL << 25)
596 : #define Py_TPFLAGS_TUPLE_SUBCLASS (1UL << 26)
597 : #define Py_TPFLAGS_BYTES_SUBCLASS (1UL << 27)
598 : #define Py_TPFLAGS_UNICODE_SUBCLASS (1UL << 28)
599 : #define Py_TPFLAGS_DICT_SUBCLASS (1UL << 29)
600 : #define Py_TPFLAGS_BASE_EXC_SUBCLASS (1UL << 30)
601 : #define Py_TPFLAGS_TYPE_SUBCLASS (1UL << 31)
602 :
603 : #define Py_TPFLAGS_DEFAULT ( \
604 : Py_TPFLAGS_HAVE_STACKLESS_EXTENSION | \
605 : 0)
606 :
607 : /* NOTE: Some of the following flags reuse lower bits (removed as part of the
608 : * Python 3.0 transition). */
609 :
610 : /* The following flags are kept for compatibility; in previous
611 : * versions they indicated presence of newer tp_* fields on the
612 : * type struct.
613 : * Starting with 3.8, binary compatibility of C extensions across
614 : * feature releases of Python is not supported anymore (except when
615 : * using the stable ABI, in which all classes are created dynamically,
616 : * using the interpreter's memory layout.)
617 : * Note that older extensions using the stable ABI set these flags,
618 : * so the bits must not be repurposed.
619 : */
620 : #define Py_TPFLAGS_HAVE_FINALIZE (1UL << 0)
621 : #define Py_TPFLAGS_HAVE_VERSION_TAG (1UL << 18)
622 :
623 :
624 : #define Py_CONSTANT_NONE 0
625 : #define Py_CONSTANT_FALSE 1
626 : #define Py_CONSTANT_TRUE 2
627 : #define Py_CONSTANT_ELLIPSIS 3
628 : #define Py_CONSTANT_NOT_IMPLEMENTED 4
629 : #define Py_CONSTANT_ZERO 5
630 : #define Py_CONSTANT_ONE 6
631 : #define Py_CONSTANT_EMPTY_STR 7
632 : #define Py_CONSTANT_EMPTY_BYTES 8
633 : #define Py_CONSTANT_EMPTY_TUPLE 9
634 :
635 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
636 : PyAPI_FUNC(PyObject*) Py_GetConstant(unsigned int constant_id);
637 : PyAPI_FUNC(PyObject*) Py_GetConstantBorrowed(unsigned int constant_id);
638 : #endif
639 :
640 :
641 : /*
642 : _Py_NoneStruct is an object of undefined type which can be used in contexts
643 : where NULL (nil) is not suitable (since NULL often means 'error').
644 : */
645 : PyAPI_DATA(PyObject) _Py_NoneStruct; /* Don't use this directly */
646 :
647 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030D0000
648 : # define Py_None Py_GetConstantBorrowed(Py_CONSTANT_NONE)
649 : #else
650 : # define Py_None (&_Py_NoneStruct)
651 : #endif
652 :
653 : // Test if an object is the None singleton, the same as "x is None" in Python.
654 : PyAPI_FUNC(int) Py_IsNone(PyObject *x);
655 : #define Py_IsNone(x) Py_Is((x), Py_None)
656 :
657 : /* Macro for returning Py_None from a function.
658 : * Only treat Py_None as immortal in the limited C API 3.12 and newer. */
659 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 < 0x030c0000
660 : # define Py_RETURN_NONE return Py_NewRef(Py_None)
661 : #else
662 : # define Py_RETURN_NONE return Py_None
663 : #endif
664 :
665 : /*
666 : Py_NotImplemented is a singleton used to signal that an operation is
667 : not implemented for a given type combination.
668 : */
669 : PyAPI_DATA(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
670 :
671 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 >= 0x030D0000
672 : # define Py_NotImplemented Py_GetConstantBorrowed(Py_CONSTANT_NOT_IMPLEMENTED)
673 : #else
674 : # define Py_NotImplemented (&_Py_NotImplementedStruct)
675 : #endif
676 :
677 : /* Macro for returning Py_NotImplemented from a function. Only treat
678 : * Py_NotImplemented as immortal in the limited C API 3.12 and newer. */
679 : #if defined(Py_LIMITED_API) && Py_LIMITED_API+0 < 0x030c0000
680 : # define Py_RETURN_NOTIMPLEMENTED return Py_NewRef(Py_NotImplemented)
681 : #else
682 : # define Py_RETURN_NOTIMPLEMENTED return Py_NotImplemented
683 : #endif
684 :
685 : /* Rich comparison opcodes */
686 : #define Py_LT 0
687 : #define Py_LE 1
688 : #define Py_EQ 2
689 : #define Py_NE 3
690 : #define Py_GT 4
691 : #define Py_GE 5
692 :
693 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000
694 : /* Result of calling PyIter_Send */
695 : typedef enum {
696 : PYGEN_RETURN = 0,
697 : PYGEN_ERROR = -1,
698 : PYGEN_NEXT = 1
699 : } PySendResult;
700 : #endif
701 :
702 : /*
703 : * Macro for implementing rich comparisons
704 : *
705 : * Needs to be a macro because any C-comparable type can be used.
706 : */
707 : #define Py_RETURN_RICHCOMPARE(val1, val2, op) \
708 : do { \
709 : switch (op) { \
710 : case Py_EQ: if ((val1) == (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
711 : case Py_NE: if ((val1) != (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
712 : case Py_LT: if ((val1) < (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
713 : case Py_GT: if ((val1) > (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
714 : case Py_LE: if ((val1) <= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
715 : case Py_GE: if ((val1) >= (val2)) Py_RETURN_TRUE; Py_RETURN_FALSE; \
716 : default: \
717 : Py_UNREACHABLE(); \
718 : } \
719 : } while (0)
720 :
721 :
722 : /*
723 : More conventions
724 : ================
725 :
726 : Argument Checking
727 : -----------------
728 :
729 : Functions that take objects as arguments normally don't check for nil
730 : arguments, but they do check the type of the argument, and return an
731 : error if the function doesn't apply to the type.
732 :
733 : Failure Modes
734 : -------------
735 :
736 : Functions may fail for a variety of reasons, including running out of
737 : memory. This is communicated to the caller in two ways: an error string
738 : is set (see errors.h), and the function result differs: functions that
739 : normally return a pointer return NULL for failure, functions returning
740 : an integer return -1 (which could be a legal return value too!), and
741 : other functions return 0 for success and -1 for failure.
742 : Callers should always check for errors before using the result. If
743 : an error was set, the caller must either explicitly clear it, or pass
744 : the error on to its caller.
745 :
746 : Reference Counts
747 : ----------------
748 :
749 : It takes a while to get used to the proper usage of reference counts.
750 :
751 : Functions that create an object set the reference count to 1; such new
752 : objects must be stored somewhere or destroyed again with Py_DECREF().
753 : Some functions that 'store' objects, such as PyTuple_SetItem() and
754 : PyList_SetItem(),
755 : don't increment the reference count of the object, since the most
756 : frequent use is to store a fresh object. Functions that 'retrieve'
757 : objects, such as PyTuple_GetItem() and PyDict_GetItemString(), also
758 : don't increment
759 : the reference count, since most frequently the object is only looked at
760 : quickly. Thus, to retrieve an object and store it again, the caller
761 : must call Py_INCREF() explicitly.
762 :
763 : NOTE: functions that 'consume' a reference count, like
764 : PyList_SetItem(), consume the reference even if the object wasn't
765 : successfully stored, to simplify error handling.
766 :
767 : It seems attractive to make other functions that take an object as
768 : argument consume a reference count; however, this may quickly get
769 : confusing (even the current practice is already confusing). Consider
770 : it carefully, it may save lots of calls to Py_INCREF() and Py_DECREF() at
771 : times.
772 : */
773 :
774 : #ifndef Py_LIMITED_API
775 : # define Py_CPYTHON_OBJECT_H
776 : # include "cpython/object.h"
777 : # undef Py_CPYTHON_OBJECT_H
778 : #endif
779 :
780 :
781 : static inline int
782 63 : PyType_HasFeature(PyTypeObject *type, unsigned long feature)
783 : {
784 : unsigned long flags;
785 : #ifdef Py_LIMITED_API
786 : // PyTypeObject is opaque in the limited C API
787 63 : flags = PyType_GetFlags(type);
788 : #else
789 : # ifdef Py_GIL_DISABLED
790 : flags = _Py_atomic_load_ulong_relaxed(&type->tp_flags);
791 : # else
792 : flags = type->tp_flags;
793 : # endif
794 : #endif
795 63 : return ((flags & feature) != 0);
796 : }
797 :
798 : #define PyType_FastSubclass(type, flag) PyType_HasFeature((type), (flag))
799 :
800 : static inline int PyType_Check(PyObject *op) {
801 : return PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_TYPE_SUBCLASS);
802 : }
803 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
804 : # define PyType_Check(op) PyType_Check(_PyObject_CAST(op))
805 : #endif
806 :
807 : #define _PyType_CAST(op) \
808 : (assert(PyType_Check(op)), _Py_CAST(PyTypeObject*, (op)))
809 :
810 : static inline int PyType_CheckExact(PyObject *op) {
811 : return Py_IS_TYPE(op, &PyType_Type);
812 : }
813 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 < 0x030b0000
814 : # define PyType_CheckExact(op) PyType_CheckExact(_PyObject_CAST(op))
815 : #endif
816 :
817 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030d0000
818 : PyAPI_FUNC(PyObject *) PyType_GetModuleByDef(PyTypeObject *, PyModuleDef *);
819 : #endif
820 :
821 : #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030e0000
822 : PyAPI_FUNC(int) PyType_Freeze(PyTypeObject *type);
823 : #endif
824 :
825 : #ifdef __cplusplus
826 : }
827 : #endif
828 : #endif // !Py_OBJECT_H
|
