| 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**); |