Debian Codegraph @

Include/cpython/object.h

raw
1 #ifndef Py_CPYTHON_OBJECT_H
2 # error "this header file must not be included directly"
3 #endif
4
5 PyAPI_FUNC(void) _Py_NewReference(PyObject *op);
6 PyAPI_FUNC(void) _Py_NewReferenceNoTotal(PyObject *op);
7 PyAPI_FUNC(void) _Py_ResurrectReference(PyObject *op);
8
9 #ifdef Py_REF_DEBUG
10 /* These are useful as debugging aids when chasing down refleaks. */
11 PyAPI_FUNC(Py_ssize_t) _Py_GetGlobalRefTotal(void);
12 # define _Py_GetRefTotal() _Py_GetGlobalRefTotal()
13 PyAPI_FUNC(Py_ssize_t) _Py_GetLegacyRefTotal(void);
14 PyAPI_FUNC(Py_ssize_t) _PyInterpreterState_GetRefTotal(PyInterpreterState *);
15 #endif
16
17
18 /********************* String Literals ****************************************/
19 /* This structure helps managing static strings. The basic usage goes like this:
20 Instead of doing
21
22 r = PyObject_CallMethod(o, "foo", "args", ...);
23
24 do
25
26 _Py_IDENTIFIER(foo);
27 ...
28 r = _PyObject_CallMethodId(o, &PyId_foo, "args", ...);
29
30 PyId_foo is a static variable, either on block level or file level. On first
31 usage, the string "foo" is interned, and the structures are linked. On interpreter
32 shutdown, all strings are released.
33
34 Alternatively, _Py_static_string allows choosing the variable name.
35 _PyUnicode_FromId returns a borrowed reference to the interned string.
36 _PyObject_{Get,Set,Has}AttrId are __getattr__ versions using _Py_Identifier*.
37 */
38 typedef struct _Py_Identifier {
39 const char* string;
40 // Index in PyInterpreterState.unicode.ids.array. It is process-wide
41 // unique and must be initialized to -1.
42 Py_ssize_t index;
43 // Hidden PyMutex struct for non free-threaded build.
44 struct {
45 uint8_t v;
46 } mutex;
47 } _Py_Identifier;
48
49 #ifndef Py_BUILD_CORE
50 // For now we are keeping _Py_IDENTIFIER for continued use
51 // in non-builtin extensions (and naughty PyPI modules).
52
53 #define _Py_static_string_init(value) { .string = (value), .index = -1 }
54 #define _Py_static_string(varname, value) static _Py_Identifier varname = _Py_static_string_init(value)
55 #define _Py_IDENTIFIER(varname) _Py_static_string(PyId_##varname, #varname)
56
57 #endif /* !Py_BUILD_CORE */
58
59
60 typedef struct {
61 /* Number implementations must check *both*
62 arguments for proper type and implement the necessary conversions
63 in the slot functions themselves. */
64
65 binaryfunc nb_add;
66 binaryfunc nb_subtract;
67 binaryfunc nb_multiply;
68 binaryfunc nb_remainder;
69 binaryfunc nb_divmod;
70 ternaryfunc nb_power;
71 unaryfunc nb_negative;
72 unaryfunc nb_positive;
73 unaryfunc nb_absolute;
74 inquiry nb_bool;
75 unaryfunc nb_invert;
76 binaryfunc nb_lshift;
77 binaryfunc nb_rshift;
78 binaryfunc nb_and;
79 binaryfunc nb_xor;
80 binaryfunc nb_or;
81 unaryfunc nb_int;
82 void *nb_reserved; /* the slot formerly known as nb_long */
83 unaryfunc nb_float;
84
85 binaryfunc nb_inplace_add;
86 binaryfunc nb_inplace_subtract;
87 binaryfunc nb_inplace_multiply;
88 binaryfunc nb_inplace_remainder;
89 ternaryfunc nb_inplace_power;
90 binaryfunc nb_inplace_lshift;
91 binaryfunc nb_inplace_rshift;
92 binaryfunc nb_inplace_and;
93 binaryfunc nb_inplace_xor;
94 binaryfunc nb_inplace_or;
95
96 binaryfunc nb_floor_divide;
97 binaryfunc nb_true_divide;
98 binaryfunc nb_inplace_floor_divide;
99 binaryfunc nb_inplace_true_divide;
100
101 unaryfunc nb_index;
102
103 binaryfunc nb_matrix_multiply;
104 binaryfunc nb_inplace_matrix_multiply;
105 } PyNumberMethods;
106
107 typedef struct {
108 lenfunc sq_length;
109 binaryfunc sq_concat;
110 ssizeargfunc sq_repeat;
111 ssizeargfunc sq_item;
112 void *was_sq_slice;
113 ssizeobjargproc sq_ass_item;
114 void *was_sq_ass_slice;
115 objobjproc sq_contains;
116
117 binaryfunc sq_inplace_concat;
118 ssizeargfunc sq_inplace_repeat;
119 } PySequenceMethods;
120
121 typedef struct {
122 lenfunc mp_length;
123 binaryfunc mp_subscript;
124 objobjargproc mp_ass_subscript;
125 } PyMappingMethods;
126
127 typedef PySendResult (*sendfunc)(PyObject *iter, PyObject *value, PyObject **result);
128
129 typedef struct {
130 unaryfunc am_await;
131 unaryfunc am_aiter;
132 unaryfunc am_anext;
133 sendfunc am_send;
134 } PyAsyncMethods;
135
136 typedef struct {
137 getbufferproc bf_getbuffer;
138 releasebufferproc bf_releasebuffer;
139 } PyBufferProcs;
140
141 /* Allow printfunc in the tp_vectorcall_offset slot for
142 * backwards-compatibility */
143 typedef Py_ssize_t printfunc;
144
145 // If this structure is modified, Doc/includes/typestruct.h should be updated
146 // as well.
147 struct _typeobject {
148 PyObject_VAR_HEAD
149 const char *tp_name; /* For printing, in format "<module>.<name>" */
150 Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */
151
152 /* Methods to implement standard operations */
153
154 destructor tp_dealloc;
155 Py_ssize_t tp_vectorcall_offset;
156 getattrfunc tp_getattr;
157 setattrfunc tp_setattr;
158 PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
159 or tp_reserved (Python 3) */
160 reprfunc tp_repr;
161
162 /* Method suites for standard classes */
163
164 PyNumberMethods *tp_as_number;
165 PySequenceMethods *tp_as_sequence;
166 PyMappingMethods *tp_as_mapping;
167
168 /* More standard operations (here for binary compatibility) */
169
170 hashfunc tp_hash;
171 ternaryfunc tp_call;
172 reprfunc tp_str;
173 getattrofunc tp_getattro;
174 setattrofunc tp_setattro;
175
176 /* Functions to access object as input/output buffer */
177 PyBufferProcs *tp_as_buffer;
178
179 /* Flags to define presence of optional/expanded features */
180 unsigned long tp_flags;
181
182 const char *tp_doc; /* Documentation string */
183
184 /* Assigned meaning in release 2.0 */
185 /* call function for all accessible objects */
186 traverseproc tp_traverse;
187
188 /* delete references to contained objects */
189 inquiry tp_clear;
190
191 /* Assigned meaning in release 2.1 */
192 /* rich comparisons */
193 richcmpfunc tp_richcompare;
194
195 /* weak reference enabler */
196 Py_ssize_t tp_weaklistoffset;
197
198 /* Iterators */
199 getiterfunc tp_iter;
200 iternextfunc tp_iternext;
201
202 /* Attribute descriptor and subclassing stuff */
203 PyMethodDef *tp_methods;
204 PyMemberDef *tp_members;
205 PyGetSetDef *tp_getset;
206 // Strong reference on a heap type, borrowed reference on a static type
207 PyTypeObject *tp_base;
208 PyObject *tp_dict;
209 descrgetfunc tp_descr_get;
210 descrsetfunc tp_descr_set;
211 Py_ssize_t tp_dictoffset;
212 initproc tp_init;
213 allocfunc tp_alloc;
214 newfunc tp_new;
215 freefunc tp_free; /* Low-level free-memory routine */
216 inquiry tp_is_gc; /* For PyObject_IS_GC */
217 PyObject *tp_bases;
218 PyObject *tp_mro; /* method resolution order */
219 PyObject *tp_cache; /* no longer used */
220 void *tp_subclasses; /* for static builtin types this is an index */
221 PyObject *tp_weaklist; /* not used for static builtin types */
222 destructor tp_del;
223
224 /* Type attribute cache version tag. Added in version 2.6.
225 * If zero, the cache is invalid and must be initialized.
226 */
227 unsigned int tp_version_tag;
228
229 destructor tp_finalize;
230 vectorcallfunc tp_vectorcall;
231
232 /* bitset of which type-watchers care about this type */
233 unsigned char tp_watched;
234
235 /* Number of tp_version_tag values used.
236 * Set to _Py_ATTR_CACHE_UNUSED if the attribute cache is
237 * disabled for this type (e.g. due to custom MRO entries).
238 * Otherwise, limited to MAX_VERSIONS_PER_CLASS (defined elsewhere).
239 */
240 uint16_t tp_versions_used;
241 };
242
243 #define _Py_ATTR_CACHE_UNUSED (30000) // (see tp_versions_used)
244
245 /* This struct is used by the specializer
246 * It should be treated as an opaque blob
247 * by code other than the specializer and interpreter. */
248 struct _specialization_cache {
249 // In order to avoid bloating the bytecode with lots of inline caches, the
250 // members of this structure have a somewhat unique contract. They are set
251 // by the specialization machinery, and are invalidated by PyType_Modified.
252 // The rules for using them are as follows:
253 // - If getitem is non-NULL, then it is the same Python function that
254 // PyType_Lookup(cls, "__getitem__") would return.
255 // - If getitem is NULL, then getitem_version is meaningless.
256 // - If getitem->func_version == getitem_version, then getitem can be called
257 // with two positional arguments and no keyword arguments, and has neither
258 // *args nor **kwargs (as required by BINARY_SUBSCR_GETITEM):
259 PyObject *getitem;
260 uint32_t getitem_version;
261 PyObject *init;
262 };
263
264 /* The *real* layout of a type object when allocated on the heap */
265 typedef struct _heaptypeobject {
266 /* Note: there's a dependency on the order of these members
267 in slotptr() in typeobject.c . */
268 PyTypeObject ht_type;
269 PyAsyncMethods as_async;
270 PyNumberMethods as_number;
271 PyMappingMethods as_mapping;
272 PySequenceMethods as_sequence; /* as_sequence comes after as_mapping,
273 so that the mapping wins when both
274 the mapping and the sequence define
275 a given operator (e.g. __getitem__).
276 see add_operators() in typeobject.c . */
277 PyBufferProcs as_buffer;
278 PyObject *ht_name, *ht_slots, *ht_qualname;
279 struct _dictkeysobject *ht_cached_keys;
280 PyObject *ht_module;
281 char *_ht_tpname; // Storage for "tp_name"; see PyType_FromModuleAndSpec
282 struct _specialization_cache _spec_cache; // For use by the specializer.
283 /* here are optional user slots, followed by the members. */
284 } PyHeapTypeObject;
285
286 PyAPI_FUNC(const char *) _PyType_Name(PyTypeObject *);
287 PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *);
288 PyAPI_FUNC(PyObject *) _PyType_LookupRef(PyTypeObject *, PyObject *);
289 PyAPI_FUNC(PyObject *) PyType_GetDict(PyTypeObject *);
290
291 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int);
292 PyAPI_FUNC(void) _Py_BreakPoint(void);
293 PyAPI_FUNC(void) _PyObject_Dump(PyObject *);
294
295 PyAPI_FUNC(PyObject*) _PyObject_GetAttrId(PyObject *, _Py_Identifier *);
296
297 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *);
298 PyAPI_FUNC(void) PyObject_CallFinalizer(PyObject *);
299 PyAPI_FUNC(int) PyObject_CallFinalizerFromDealloc(PyObject *);
300
301 PyAPI_FUNC(void) PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *);
302
303 /* Same as PyObject_Generic{Get,Set}Attr, but passing the attributes
304 dict as the last parameter. */
305 PyAPI_FUNC(PyObject *)
306 _PyObject_GenericGetAttrWithDict(PyObject *, PyObject *, PyObject *, int);
307 PyAPI_FUNC(int)
308 _PyObject_GenericSetAttrWithDict(PyObject *, PyObject *,
309 PyObject *, PyObject *);
310
311 PyAPI_FUNC(PyObject *) _PyObject_FunctionStr(PyObject *);
312
313 /* Safely decref `dst` and set `dst` to `src`.
314 *
315 * As in case of Py_CLEAR "the obvious" code can be deadly:
316 *
317 * Py_DECREF(dst);
318 * dst = src;
319 *
320 * The safe way is:
321 *
322 * Py_SETREF(dst, src);
323 *
324 * That arranges to set `dst` to `src` _before_ decref'ing, so that any code
325 * triggered as a side-effect of `dst` getting torn down no longer believes
326 * `dst` points to a valid object.
327 *
328 * Temporary variables are used to only evalutate macro arguments once and so
329 * avoid the duplication of side effects. _Py_TYPEOF() or memcpy() is used to
330 * avoid a miscompilation caused by type punning. See Py_CLEAR() comment for
331 * implementation details about type punning.
332 *
333 * The memcpy() implementation does not emit a compiler warning if 'src' has
334 * not the same type than 'src': any pointer type is accepted for 'src'.
335 */
336 #ifdef _Py_TYPEOF
337 #define Py_SETREF(dst, src) \
338 do { \
339 _Py_TYPEOF(dst)* _tmp_dst_ptr = &(dst); \
340 _Py_TYPEOF(dst) _tmp_old_dst = (*_tmp_dst_ptr); \
341 *_tmp_dst_ptr = (src); \
342 Py_DECREF(_tmp_old_dst); \
343 } while (0)
344 #else
345 #define Py_SETREF(dst, src) \
346 do { \
347 PyObject **_tmp_dst_ptr = _Py_CAST(PyObject**, &(dst)); \
348 PyObject *_tmp_old_dst = (*_tmp_dst_ptr); \
349 PyObject *_tmp_src = _PyObject_CAST(src); \
350 memcpy(_tmp_dst_ptr, &_tmp_src, sizeof(PyObject*)); \
351 Py_DECREF(_tmp_old_dst); \
352 } while (0)
353 #endif
354
355 /* Py_XSETREF() is a variant of Py_SETREF() that uses Py_XDECREF() instead of
356 * Py_DECREF().
357 */
358 #ifdef _Py_TYPEOF
359 #define Py_XSETREF(dst, src) \
360 do { \
361 _Py_TYPEOF(dst)* _tmp_dst_ptr = &(dst); \
362 _Py_TYPEOF(dst) _tmp_old_dst = (*_tmp_dst_ptr); \
363 *_tmp_dst_ptr = (src); \
364 Py_XDECREF(_tmp_old_dst); \
365 } while (0)
366 #else
367 #define Py_XSETREF(dst, src) \
368 do { \
369 PyObject **_tmp_dst_ptr = _Py_CAST(PyObject**, &(dst)); \
370 PyObject *_tmp_old_dst = (*_tmp_dst_ptr); \
371 PyObject *_tmp_src = _PyObject_CAST(src); \
372 memcpy(_tmp_dst_ptr, &_tmp_src, sizeof(PyObject*)); \
373 Py_XDECREF(_tmp_old_dst); \
374 } while (0)
375 #endif
376
377
378 /* Define a pair of assertion macros:
379 _PyObject_ASSERT_FROM(), _PyObject_ASSERT_WITH_MSG() and _PyObject_ASSERT().
380
381 These work like the regular C assert(), in that they will abort the
382 process with a message on stderr if the given condition fails to hold,
383 but compile away to nothing if NDEBUG is defined.
384
385 However, before aborting, Python will also try to call _PyObject_Dump() on
386 the given object. This may be of use when investigating bugs in which a
387 particular object is corrupt (e.g. buggy a tp_visit method in an extension
388 module breaking the garbage collector), to help locate the broken objects.
389
390 The WITH_MSG variant allows you to supply an additional message that Python
391 will attempt to print to stderr, after the object dump. */
392 #ifdef NDEBUG
393 /* No debugging: compile away the assertions: */
394 # define _PyObject_ASSERT_FROM(obj, expr, msg, filename, lineno, func) \
395 ((void)0)
396 #else
397 /* With debugging: generate checks: */
398 # define _PyObject_ASSERT_FROM(obj, expr, msg, filename, lineno, func) \
399 ((expr) \
400 ? (void)(0) \
401 : _PyObject_AssertFailed((obj), Py_STRINGIFY(expr), \
402 (msg), (filename), (lineno), (func)))
403 #endif
404
405 #define _PyObject_ASSERT_WITH_MSG(obj, expr, msg) \
406 _PyObject_ASSERT_FROM((obj), expr, (msg), __FILE__, __LINE__, __func__)
407 #define _PyObject_ASSERT(obj, expr) \
408 _PyObject_ASSERT_WITH_MSG((obj), expr, NULL)
409
410 #define _PyObject_ASSERT_FAILED_MSG(obj, msg) \
411 _PyObject_AssertFailed((obj), NULL, (msg), __FILE__, __LINE__, __func__)
412
413 /* Declare and define _PyObject_AssertFailed() even when NDEBUG is defined,
414 to avoid causing compiler/linker errors when building extensions without
415 NDEBUG against a Python built with NDEBUG defined.
416
417 msg, expr and function can be NULL. */
418 PyAPI_FUNC(void) _Py_NO_RETURN _PyObject_AssertFailed(
419 PyObject *obj,
420 const char *expr,
421 const char *msg,
422 const char *file,
423 int line,
424 const char *function);
425
426
427 /* Trashcan mechanism, thanks to Christian Tismer.
428
429 When deallocating a container object, it's possible to trigger an unbounded
430 chain of deallocations, as each Py_DECREF in turn drops the refcount on "the
431 next" object in the chain to 0. This can easily lead to stack overflows,
432 especially in threads (which typically have less stack space to work with).
433
434 A container object can avoid this by bracketing the body of its tp_dealloc
435 function with a pair of macros:
436
437 static void
438 mytype_dealloc(mytype *p)
439 {
440 ... declarations go here ...
441
442 PyObject_GC_UnTrack(p); // must untrack first
443 Py_TRASHCAN_BEGIN(p, mytype_dealloc)
444 ... The body of the deallocator goes here, including all calls ...
445 ... to Py_DECREF on contained objects. ...
446 Py_TRASHCAN_END // there should be no code after this
447 }
448
449 CAUTION: Never return from the middle of the body! If the body needs to
450 "get out early", put a label immediately before the Py_TRASHCAN_END
451 call, and goto it. Else the call-depth counter (see below) will stay
452 above 0 forever, and the trashcan will never get emptied.
453
454 How it works: The BEGIN macro increments a call-depth counter. So long
455 as this counter is small, the body of the deallocator is run directly without
456 further ado. But if the counter gets large, it instead adds p to a list of
457 objects to be deallocated later, skips the body of the deallocator, and
458 resumes execution after the END macro. The tp_dealloc routine then returns
459 without deallocating anything (and so unbounded call-stack depth is avoided).
460
461 When the call stack finishes unwinding again, code generated by the END macro
462 notices this, and calls another routine to deallocate all the objects that
463 may have been added to the list of deferred deallocations. In effect, a
464 chain of N deallocations is broken into (N-1)/(Py_TRASHCAN_HEADROOM-1) pieces,
465 with the call stack never exceeding a depth of Py_TRASHCAN_HEADROOM.
466
467 Since the tp_dealloc of a subclass typically calls the tp_dealloc of the base
468 class, we need to ensure that the trashcan is only triggered on the tp_dealloc
469 of the actual class being deallocated. Otherwise we might end up with a
470 partially-deallocated object. To check this, the tp_dealloc function must be
471 passed as second argument to Py_TRASHCAN_BEGIN().
472 */
473
474 /* Python 3.9 private API, invoked by the macros below. */
475 PyAPI_FUNC(int) _PyTrash_begin(PyThreadState *tstate, PyObject *op);
476 PyAPI_FUNC(void) _PyTrash_end(PyThreadState *tstate);
477
478 PyAPI_FUNC(void) _PyTrash_thread_deposit_object(PyThreadState *tstate, PyObject *op);
479 PyAPI_FUNC(void) _PyTrash_thread_destroy_chain(PyThreadState *tstate);
480
481
482 /* Python 3.10 private API, invoked by the Py_TRASHCAN_BEGIN(). */
483
484 /* To avoid raising recursion errors during dealloc trigger trashcan before we reach
485 * recursion limit. To avoid trashing, we don't attempt to empty the trashcan until
486 * we have headroom above the trigger limit */
487 #define Py_TRASHCAN_HEADROOM 50
488
489 #define Py_TRASHCAN_BEGIN(op, dealloc) \
490 do { \
491 PyThreadState *tstate = PyThreadState_Get(); \
492 if (tstate->c_recursion_remaining <= Py_TRASHCAN_HEADROOM && Py_TYPE(op)->tp_dealloc == (destructor)dealloc) { \
493 _PyTrash_thread_deposit_object(tstate, (PyObject *)op); \
494 break; \
495 } \
496 tstate->c_recursion_remaining--;
497 /* The body of the deallocator is here. */
498 #define Py_TRASHCAN_END \
499 tstate->c_recursion_remaining++; \
500 if (tstate->delete_later && tstate->c_recursion_remaining > (Py_TRASHCAN_HEADROOM*2)) { \
501 _PyTrash_thread_destroy_chain(tstate); \
502 } \
503 } while (0);
504
505
506 PyAPI_FUNC(void *) PyObject_GetItemData(PyObject *obj);
507
508 PyAPI_FUNC(int) PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg);
509 PyAPI_FUNC(int) _PyObject_SetManagedDict(PyObject *obj, PyObject *new_dict);
510 PyAPI_FUNC(void) PyObject_ClearManagedDict(PyObject *obj);
511
512 #define TYPE_MAX_WATCHERS 8
513
514 typedef int(*PyType_WatchCallback)(PyTypeObject *);
515 PyAPI_FUNC(int) PyType_AddWatcher(PyType_WatchCallback callback);
516 PyAPI_FUNC(int) PyType_ClearWatcher(int watcher_id);
517 PyAPI_FUNC(int) PyType_Watch(int watcher_id, PyObject *type);
518 PyAPI_FUNC(int) PyType_Unwatch(int watcher_id, PyObject *type);
519
520 /* Attempt to assign a version tag to the given type.
521 *
522 * Returns 1 if the type already had a valid version tag or a new one was
523 * assigned, or 0 if a new tag could not be assigned.
524 */
525 PyAPI_FUNC(int) PyUnstable_Type_AssignVersionTag(PyTypeObject *type);
526
527
528 typedef enum {
529 PyRefTracer_CREATE = 0,
530 PyRefTracer_DESTROY = 1,
531 } PyRefTracerEvent;
532
533 typedef int (*PyRefTracer)(PyObject *, PyRefTracerEvent event, void *);
534 PyAPI_FUNC(int) PyRefTracer_SetTracer(PyRefTracer tracer, void *data);
535 PyAPI_FUNC(PyRefTracer) PyRefTracer_GetTracer(void**);