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