1 #ifndef Py_INTERNAL_OBJECT_H
2 #define Py_INTERNAL_OBJECT_H
3 #ifdef __cplusplus
4 extern "C" {
5 #endif
6
7 #ifndef Py_BUILD_CORE
8 # error "this header requires Py_BUILD_CORE define"
9 #endif
10
11 #include <stdbool.h>
12 #include "pycore_gc.h" // _PyObject_GC_IS_TRACKED()
13 #include "pycore_interp.h" // PyInterpreterState.gc
14 #include "pycore_pystate.h" // _PyInterpreterState_GET()
15 #include "pycore_runtime.h" // _PyRuntime
16
17 /* We need to maintain an internal copy of Py{Var}Object_HEAD_INIT to avoid
18 designated initializer conflicts in C++20. If we use the deinition in
19 object.h, we will be mixing designated and non-designated initializers in
20 pycore objects which is forbiddent in C++20. However, if we then use
21 designated initializers in object.h then Extensions without designated break.
22 Furthermore, we can't use designated initializers in Extensions since these
23 are not supported pre-C++20. Thus, keeping an internal copy here is the most
24 backwards compatible solution */
25 #define _PyObject_HEAD_INIT(type) \
26 { \
27 _PyObject_EXTRA_INIT \
28 .ob_refcnt = _Py_IMMORTAL_REFCNT, \
29 .ob_type = (type) \
30 },
31 #define _PyVarObject_HEAD_INIT(type, size) \
32 { \
33 .ob_base = _PyObject_HEAD_INIT(type) \
34 .ob_size = size \
35 },
36
37 PyAPI_FUNC(void) _Py_NO_RETURN _Py_FatalRefcountErrorFunc(
38 const char *func,
39 const char *message);
40
41 #define _Py_FatalRefcountError(message) \
42 _Py_FatalRefcountErrorFunc(__func__, (message))
43
44
45 #ifdef Py_REF_DEBUG
46 /* The symbol is only exposed in the API for the sake of extensions
47 built against the pre-3.12 stable ABI. */
48 PyAPI_DATA(Py_ssize_t) _Py_RefTotal;
49
50 extern void _Py_AddRefTotal(PyInterpreterState *, Py_ssize_t);
51 extern void _Py_IncRefTotal(PyInterpreterState *);
52 extern void _Py_DecRefTotal(PyInterpreterState *);
53
54 # define _Py_DEC_REFTOTAL(interp) \
55 interp->object_state.reftotal--
56 #endif
57
58 // Increment reference count by n
59 static inline void _Py_RefcntAdd(PyObject* op, Py_ssize_t n)
60 {
61 if (_Py_IsImmortal(op)) {
62 return;
63 }
64 #ifdef Py_REF_DEBUG
65 _Py_AddRefTotal(_PyInterpreterState_GET(), n);
66 #endif
67 op->ob_refcnt += n;
68 }
69 #define _Py_RefcntAdd(op, n) _Py_RefcntAdd(_PyObject_CAST(op), n)
70
71 static inline void _Py_SetImmortal(PyObject *op)
72 {
73 if (op) {
74 op->ob_refcnt = _Py_IMMORTAL_REFCNT;
75 }
76 }
77 #define _Py_SetImmortal(op) _Py_SetImmortal(_PyObject_CAST(op))
78
79 /* _Py_ClearImmortal() should only be used during runtime finalization. */
80 static inline void _Py_ClearImmortal(PyObject *op)
81 {
82 if (op) {
83 assert(op->ob_refcnt == _Py_IMMORTAL_REFCNT);
84 op->ob_refcnt = 1;
85 Py_DECREF(op);
86 }
87 }
88 #define _Py_ClearImmortal(op) \
89 do { \
90 _Py_ClearImmortal(_PyObject_CAST(op)); \
91 op = NULL; \
92 } while (0)
93
94 static inline void
95 _Py_DECREF_SPECIALIZED(PyObject *op, const destructor destruct)
96 {
97 if (_Py_IsImmortal(op)) {
98 return;
99 }
100 _Py_DECREF_STAT_INC();
101 #ifdef Py_REF_DEBUG
102 _Py_DEC_REFTOTAL(_PyInterpreterState_GET());
103 #endif
104 if (--op->ob_refcnt != 0) {
105 assert(op->ob_refcnt > 0);
106 }
107 else {
108 #ifdef Py_TRACE_REFS
109 _Py_ForgetReference(op);
110 #endif
111 destruct(op);
112 }
113 }
114
115 static inline void
116 _Py_DECREF_NO_DEALLOC(PyObject *op)
117 {
118 if (_Py_IsImmortal(op)) {
119 return;
120 }
121 _Py_DECREF_STAT_INC();
122 #ifdef Py_REF_DEBUG
123 _Py_DEC_REFTOTAL(_PyInterpreterState_GET());
124 #endif
125 op->ob_refcnt--;
126 #ifdef Py_DEBUG
127 if (op->ob_refcnt <= 0) {
128 _Py_FatalRefcountError("Expected a positive remaining refcount");
129 }
130 #endif
131 }
132
133 #ifdef Py_REF_DEBUG
134 # undef _Py_DEC_REFTOTAL
135 #endif
136
137
138 PyAPI_FUNC(int) _PyType_CheckConsistency(PyTypeObject *type);
139 PyAPI_FUNC(int) _PyDict_CheckConsistency(PyObject *mp, int check_content);
140
141 /* Update the Python traceback of an object. This function must be called
142 when a memory block is reused from a free list.
143
144 Internal function called by _Py_NewReference(). */
145 extern int _PyTraceMalloc_NewReference(PyObject *op);
146
147 // Fast inlined version of PyType_HasFeature()
148 static inline int
149 _PyType_HasFeature(PyTypeObject *type, unsigned long feature) {
150 return ((type->tp_flags & feature) != 0);
151 }
152
153 extern void _PyType_InitCache(PyInterpreterState *interp);
154
155 extern void _PyObject_InitState(PyInterpreterState *interp);
156
157 /* Inline functions trading binary compatibility for speed:
158 _PyObject_Init() is the fast version of PyObject_Init(), and
159 _PyObject_InitVar() is the fast version of PyObject_InitVar().
160
161 These inline functions must not be called with op=NULL. */
162 static inline void
163 _PyObject_Init(PyObject *op, PyTypeObject *typeobj)
164 {
165 assert(op != NULL);
166 Py_SET_TYPE(op, typeobj);
167 if (_PyType_HasFeature(typeobj, Py_TPFLAGS_HEAPTYPE)) {
168 Py_INCREF(typeobj);
169 }
170 _Py_NewReference(op);
171 }
172
173 static inline void
174 _PyObject_InitVar(PyVarObject *op, PyTypeObject *typeobj, Py_ssize_t size)
175 {
176 assert(op != NULL);
177 assert(typeobj != &PyLong_Type);
178 _PyObject_Init((PyObject *)op, typeobj);
179 Py_SET_SIZE(op, size);
180 }
181
182
183 /* Tell the GC to track this object.
184 *
185 * The object must not be tracked by the GC.
186 *
187 * NB: While the object is tracked by the collector, it must be safe to call the
188 * ob_traverse method.
189 *
190 * Internal note: interp->gc.generation0->_gc_prev doesn't have any bit flags
191 * because it's not object header. So we don't use _PyGCHead_PREV() and
192 * _PyGCHead_SET_PREV() for it to avoid unnecessary bitwise operations.
193 *
194 * See also the public PyObject_GC_Track() function.
195 */
196 static inline void _PyObject_GC_TRACK(
197 // The preprocessor removes _PyObject_ASSERT_FROM() calls if NDEBUG is defined
198 #ifndef NDEBUG
199 const char *filename, int lineno,
200 #endif
201 PyObject *op)
202 {
203 _PyObject_ASSERT_FROM(op, !_PyObject_GC_IS_TRACKED(op),
204 "object already tracked by the garbage collector",
205 filename, lineno, __func__);
206
207 PyGC_Head *gc = _Py_AS_GC(op);
208 _PyObject_ASSERT_FROM(op,
209 (gc->_gc_prev & _PyGC_PREV_MASK_COLLECTING) == 0,
210 "object is in generation which is garbage collected",
211 filename, lineno, __func__);
212
213 PyInterpreterState *interp = _PyInterpreterState_GET();
214 PyGC_Head *generation0 = interp->gc.generation0;
215 PyGC_Head *last = (PyGC_Head*)(generation0->_gc_prev);
216 _PyGCHead_SET_NEXT(last, gc);
217 _PyGCHead_SET_PREV(gc, last);
218 _PyGCHead_SET_NEXT(gc, generation0);
219 generation0->_gc_prev = (uintptr_t)gc;
220 }
221
222 /* Tell the GC to stop tracking this object.
223 *
224 * Internal note: This may be called while GC. So _PyGC_PREV_MASK_COLLECTING
225 * must be cleared. But _PyGC_PREV_MASK_FINALIZED bit is kept.
226 *
227 * The object must be tracked by the GC.
228 *
229 * See also the public PyObject_GC_UnTrack() which accept an object which is
230 * not tracked.
231 */
232 static inline void _PyObject_GC_UNTRACK(
233 // The preprocessor removes _PyObject_ASSERT_FROM() calls if NDEBUG is defined
234 #ifndef NDEBUG
235 const char *filename, int lineno,
236 #endif
237 PyObject *op)
238 {
239 _PyObject_ASSERT_FROM(op, _PyObject_GC_IS_TRACKED(op),
240 "object not tracked by the garbage collector",
241 filename, lineno, __func__);
242
243 PyGC_Head *gc = _Py_AS_GC(op);
244 PyGC_Head *prev = _PyGCHead_PREV(gc);
245 PyGC_Head *next = _PyGCHead_NEXT(gc);
246 _PyGCHead_SET_NEXT(prev, next);
247 _PyGCHead_SET_PREV(next, prev);
248 gc->_gc_next = 0;
249 gc->_gc_prev &= _PyGC_PREV_MASK_FINALIZED;
250 }
251
252 // Macros to accept any type for the parameter, and to automatically pass
253 // the filename and the filename (if NDEBUG is not defined) where the macro
254 // is called.
255 #ifdef NDEBUG
256 # define _PyObject_GC_TRACK(op) \
257 _PyObject_GC_TRACK(_PyObject_CAST(op))
258 # define _PyObject_GC_UNTRACK(op) \
259 _PyObject_GC_UNTRACK(_PyObject_CAST(op))
260 #else
261 # define _PyObject_GC_TRACK(op) \
262 _PyObject_GC_TRACK(__FILE__, __LINE__, _PyObject_CAST(op))
263 # define _PyObject_GC_UNTRACK(op) \
264 _PyObject_GC_UNTRACK(__FILE__, __LINE__, _PyObject_CAST(op))
265 #endif
266
267 #ifdef Py_REF_DEBUG
268 extern void _PyInterpreterState_FinalizeRefTotal(PyInterpreterState *);
269 extern void _Py_FinalizeRefTotal(_PyRuntimeState *);
270 extern void _PyDebug_PrintTotalRefs(void);
271 #endif
272
273 #ifdef Py_TRACE_REFS
274 extern void _Py_AddToAllObjects(PyObject *op, int force);
275 extern void _Py_PrintReferences(PyInterpreterState *, FILE *);
276 extern void _Py_PrintReferenceAddresses(PyInterpreterState *, FILE *);
277 #endif
278
279
280 /* Return the *address* of the object's weaklist. The address may be
281 * dereferenced to get the current head of the weaklist. This is useful
282 * for iterating over the linked list of weakrefs, especially when the
283 * list is being modified externally (e.g. refs getting removed).
284 *
285 * The returned pointer should not be used to change the head of the list
286 * nor should it be used to add, remove, or swap any refs in the list.
287 * That is the sole responsibility of the code in weakrefobject.c.
288 */
289 static inline PyObject **
290 _PyObject_GET_WEAKREFS_LISTPTR(PyObject *op)
291 {
292 if (PyType_Check(op) &&
293 ((PyTypeObject *)op)->tp_flags & _Py_TPFLAGS_STATIC_BUILTIN) {
294 PyInterpreterState *interp = _PyInterpreterState_GET();
295 static_builtin_state *state = _PyStaticType_GetState(
296 interp, (PyTypeObject *)op);
297 return _PyStaticType_GET_WEAKREFS_LISTPTR(state);
298 }
299 // Essentially _PyObject_GET_WEAKREFS_LISTPTR_FROM_OFFSET():
300 Py_ssize_t offset = Py_TYPE(op)->tp_weaklistoffset;
301 return (PyObject **)((char *)op + offset);
302 }
303
304 /* This is a special case of _PyObject_GET_WEAKREFS_LISTPTR().
305 * Only the most fundamental lookup path is used.
306 * Consequently, static types should not be used.
307 *
308 * For static builtin types the returned pointer will always point
309 * to a NULL tp_weaklist. This is fine for any deallocation cases,
310 * since static types are never deallocated and static builtin types
311 * are only finalized at the end of runtime finalization.
312 *
313 * If the weaklist for static types is actually needed then use
314 * _PyObject_GET_WEAKREFS_LISTPTR().
315 */
316 static inline PyWeakReference **
317 _PyObject_GET_WEAKREFS_LISTPTR_FROM_OFFSET(PyObject *op)
318 {
319 assert(!PyType_Check(op) ||
320 ((PyTypeObject *)op)->tp_flags & Py_TPFLAGS_HEAPTYPE);
321 Py_ssize_t offset = Py_TYPE(op)->tp_weaklistoffset;
322 return (PyWeakReference **)((char *)op + offset);
323 }
324
325
326 // Fast inlined version of PyObject_IS_GC()
327 static inline int
328 _PyObject_IS_GC(PyObject *obj)
329 {
330 return (PyType_IS_GC(Py_TYPE(obj))
331 && (Py_TYPE(obj)->tp_is_gc == NULL
332 || Py_TYPE(obj)->tp_is_gc(obj)));
333 }
334
335 // Fast inlined version of PyType_IS_GC()
336 #define _PyType_IS_GC(t) _PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC)
337
338 static inline size_t
339 _PyType_PreHeaderSize(PyTypeObject *tp)
340 {
341 return _PyType_IS_GC(tp) * sizeof(PyGC_Head) +
342 _PyType_HasFeature(tp, Py_TPFLAGS_PREHEADER) * 2 * sizeof(PyObject *);
343 }
344
345 void _PyObject_GC_Link(PyObject *op);
346
347 // Usage: assert(_Py_CheckSlotResult(obj, "__getitem__", result != NULL));
348 extern int _Py_CheckSlotResult(
349 PyObject *obj,
350 const char *slot_name,
351 int success);
352
353 // Test if a type supports weak references
354 static inline int _PyType_SUPPORTS_WEAKREFS(PyTypeObject *type) {
355 return (type->tp_weaklistoffset != 0);
356 }
357
358 extern PyObject* _PyType_AllocNoTrack(PyTypeObject *type, Py_ssize_t nitems);
359
360 extern int _PyObject_InitializeDict(PyObject *obj);
361 extern int _PyObject_StoreInstanceAttribute(PyObject *obj, PyDictValues *values,
362 PyObject *name, PyObject *value);
363 PyObject * _PyObject_GetInstanceAttribute(PyObject *obj, PyDictValues *values,
364 PyObject *name);
365
366 typedef union {
367 PyObject *dict;
368 /* Use a char* to generate a warning if directly assigning a PyDictValues */
369 char *values;
370 } PyDictOrValues;
371
372 static inline PyDictOrValues *
373 _PyObject_DictOrValuesPointer(PyObject *obj)
374 {
375 assert(Py_TYPE(obj)->tp_flags & Py_TPFLAGS_MANAGED_DICT);
376 return ((PyDictOrValues *)obj)-3;
377 }
378
379 static inline int
380 _PyDictOrValues_IsValues(PyDictOrValues dorv)
381 {
382 return ((uintptr_t)dorv.values) & 1;
383 }
384
385 static inline PyDictValues *
386 _PyDictOrValues_GetValues(PyDictOrValues dorv)
387 {
388 assert(_PyDictOrValues_IsValues(dorv));
389 return (PyDictValues *)(dorv.values + 1);
390 }
391
392 static inline PyObject *
393 _PyDictOrValues_GetDict(PyDictOrValues dorv)
394 {
395 assert(!_PyDictOrValues_IsValues(dorv));
396 return dorv.dict;
397 }
398
399 static inline void
400 _PyDictOrValues_SetValues(PyDictOrValues *ptr, PyDictValues *values)
401 {
402 ptr->values = ((char *)values) - 1;
403 }
404
405 #define MANAGED_WEAKREF_OFFSET (((Py_ssize_t)sizeof(PyObject *))*-4)
406
407 extern PyObject ** _PyObject_ComputedDictPointer(PyObject *);
408 extern void _PyObject_FreeInstanceAttributes(PyObject *obj);
409 extern int _PyObject_IsInstanceDictEmpty(PyObject *);
410
411 PyAPI_FUNC(PyObject *) _PyObject_LookupSpecial(PyObject *, PyObject *);
412
413 /* C function call trampolines to mitigate bad function pointer casts.
414 *
415 * Typical native ABIs ignore additional arguments or fill in missing
416 * values with 0/NULL in function pointer cast. Compilers do not show
417 * warnings when a function pointer is explicitly casted to an
418 * incompatible type.
419 *
420 * Bad fpcasts are an issue in WebAssembly. WASM's indirect_call has strict
421 * function signature checks. Argument count, types, and return type must
422 * match.
423 *
424 * Third party code unintentionally rely on problematic fpcasts. The call
425 * trampoline mitigates common occurrences of bad fpcasts on Emscripten.
426 */
427 #if defined(__EMSCRIPTEN__) && defined(PY_CALL_TRAMPOLINE)
428 #define _PyCFunction_TrampolineCall(meth, self, args) \
429 _PyCFunctionWithKeywords_TrampolineCall( \
430 (*(PyCFunctionWithKeywords)(void(*)(void))(meth)), (self), (args), NULL)
431 extern PyObject* _PyCFunctionWithKeywords_TrampolineCall(
432 PyCFunctionWithKeywords meth, PyObject *, PyObject *, PyObject *);
433 #else
434 #define _PyCFunction_TrampolineCall(meth, self, args) \
435 (meth)((self), (args))
436 #define _PyCFunctionWithKeywords_TrampolineCall(meth, self, args, kw) \
437 (meth)((self), (args), (kw))
438 #endif // __EMSCRIPTEN__ && PY_CALL_TRAMPOLINE
439
440 #ifdef __cplusplus
441 }
442 #endif
443 #endif /* !Py_INTERNAL_OBJECT_H */