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

source code of include/python3.10/cpython/object.h