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