1 #ifndef Py_CPYTHON_PYSTATE_H 2 # error "this header file must not be included directly" 3 #endif 4 5 6 PyAPI_FUNC(int) _PyInterpreterState_RequiresIDRef(PyInterpreterState *); 7 PyAPI_FUNC(void) _PyInterpreterState_RequireIDRef(PyInterpreterState *, int); 8 9 PyAPI_FUNC(PyObject *) _PyInterpreterState_GetMainModule(PyInterpreterState *); 10 11 /* State unique per thread */ 12 13 /* Py_tracefunc return -1 when raising an exception, or 0 for success. */ 14 typedef int (*Py_tracefunc)(PyObject *, PyFrameObject *, int, PyObject *); 15 16 /* The following values are used for 'what' for tracefunc functions 17 * 18 * To add a new kind of trace event, also update "trace_init" in 19 * Python/sysmodule.c to define the Python level event name 20 */ 21 #define PyTrace_CALL 0 22 #define PyTrace_EXCEPTION 1 23 #define PyTrace_LINE 2 24 #define PyTrace_RETURN 3 25 #define PyTrace_C_CALL 4 26 #define PyTrace_C_EXCEPTION 5 27 #define PyTrace_C_RETURN 6 28 #define PyTrace_OPCODE 7 29 30 31 typedef struct { 32 PyCodeObject *code; // The code object for the bounds. May be NULL. 33 PyCodeAddressRange bounds; // Only valid if code != NULL. 34 } PyTraceInfo; 35 36 // Internal structure: you should not use it directly, but use public functions 37 // like PyThreadState_EnterTracing() and PyThreadState_LeaveTracing(). 38 typedef struct _PyCFrame { 39 /* This struct will be threaded through the C stack 40 * allowing fast access to per-thread state that needs 41 * to be accessed quickly by the interpreter, but can 42 * be modified outside of the interpreter. 43 * 44 * WARNING: This makes data on the C stack accessible from 45 * heap objects. Care must be taken to maintain stack 46 * discipline and make sure that instances of this struct cannot 47 * accessed outside of their lifetime. 48 */ 49 uint8_t use_tracing; // 0 or 255 (or'ed into opcode, hence 8-bit type) 50 /* Pointer to the currently executing frame (it can be NULL) */ 51 struct _PyInterpreterFrame *current_frame; 52 struct _PyCFrame *previous; 53 } _PyCFrame; 54 55 typedef struct _err_stackitem { 56 /* This struct represents a single execution context where we might 57 * be currently handling an exception. It is a per-coroutine state 58 * (coroutine in the computer science sense, including the thread 59 * and generators). 60 * 61 * This is used as an entry on the exception stack, where each 62 * entry indicates if it is currently handling an exception. 63 * This ensures that the exception state is not impacted 64 * by "yields" from an except handler. The thread 65 * always has an entry (the bottom-most one). 66 */ 67 68 /* The exception currently being handled in this context, if any. */ 69 PyObject *exc_value; 70 71 struct _err_stackitem *previous_item; 72 73 } _PyErr_StackItem; 74 75 typedef struct _stack_chunk { 76 struct _stack_chunk *previous; 77 size_t size; 78 size_t top; 79 PyObject * data[1]; /* Variable sized */ 80 } _PyStackChunk; 81 82 struct _ts { 83 /* See Python/ceval.c for comments explaining most fields */ 84 85 PyThreadState *prev; 86 PyThreadState *next; 87 PyInterpreterState *interp; 88 89 /* Has been initialized to a safe state. 90 91 In order to be effective, this must be set to 0 during or right 92 after allocation. */ 93 int _initialized; 94 95 /* Was this thread state statically allocated? */ 96 int _static; 97 98 int recursion_remaining; 99 int recursion_limit; 100 int recursion_headroom; /* Allow 50 more calls to handle any errors. */ 101 102 /* 'tracing' keeps track of the execution depth when tracing/profiling. 103 This is to prevent the actual trace/profile code from being recorded in 104 the trace/profile. */ 105 int tracing; 106 int tracing_what; /* The event currently being traced, if any. */ 107 108 /* Pointer to current _PyCFrame in the C stack frame of the currently, 109 * or most recently, executing _PyEval_EvalFrameDefault. */ 110 _PyCFrame *cframe; 111 112 Py_tracefunc c_profilefunc; 113 Py_tracefunc c_tracefunc; 114 PyObject *c_profileobj; 115 PyObject *c_traceobj; 116 117 /* The exception currently being raised */ 118 PyObject *curexc_type; 119 PyObject *curexc_value; 120 PyObject *curexc_traceback; 121 122 /* Pointer to the top of the exception stack for the exceptions 123 * we may be currently handling. (See _PyErr_StackItem above.) 124 * This is never NULL. */ 125 _PyErr_StackItem *exc_info; 126 127 PyObject *dict; /* Stores per-thread state */ 128 129 int gilstate_counter; 130 131 PyObject *async_exc; /* Asynchronous exception to raise */ 132 unsigned long thread_id; /* Thread id where this tstate was created */ 133 134 /* Native thread id where this tstate was created. This will be 0 except on 135 * those platforms that have the notion of native thread id, for which the 136 * macro PY_HAVE_THREAD_NATIVE_ID is then defined. 137 */ 138 unsigned long native_thread_id; 139 140 int trash_delete_nesting; 141 PyObject *trash_delete_later; 142 143 /* Called when a thread state is deleted normally, but not when it 144 * is destroyed after fork(). 145 * Pain: to prevent rare but fatal shutdown errors (issue 18808), 146 * Thread.join() must wait for the join'ed thread's tstate to be unlinked 147 * from the tstate chain. That happens at the end of a thread's life, 148 * in pystate.c. 149 * The obvious way doesn't quite work: create a lock which the tstate 150 * unlinking code releases, and have Thread.join() wait to acquire that 151 * lock. The problem is that we _are_ at the end of the thread's life: 152 * if the thread holds the last reference to the lock, decref'ing the 153 * lock will delete the lock, and that may trigger arbitrary Python code 154 * if there's a weakref, with a callback, to the lock. But by this time 155 * _PyRuntime.gilstate.tstate_current is already NULL, so only the simplest 156 * of C code can be allowed to run (in particular it must not be possible to 157 * release the GIL). 158 * So instead of holding the lock directly, the tstate holds a weakref to 159 * the lock: that's the value of on_delete_data below. Decref'ing a 160 * weakref is harmless. 161 * on_delete points to _threadmodule.c's static release_sentinel() function. 162 * After the tstate is unlinked, release_sentinel is called with the 163 * weakref-to-lock (on_delete_data) argument, and release_sentinel releases 164 * the indirectly held lock. 165 */ 166 void (*on_delete)(void *); 167 void *on_delete_data; 168 169 int coroutine_origin_tracking_depth; 170 171 PyObject *async_gen_firstiter; 172 PyObject *async_gen_finalizer; 173 174 PyObject *context; 175 uint64_t context_ver; 176 177 /* Unique thread state id. */ 178 uint64_t id; 179 180 PyTraceInfo trace_info; 181 182 _PyStackChunk *datastack_chunk; 183 PyObject **datastack_top; 184 PyObject **datastack_limit; 185 /* XXX signal handlers should also be here */ 186 187 /* The following fields are here to avoid allocation during init. 188 The data is exposed through PyThreadState pointer fields. 189 These fields should not be accessed directly outside of init. 190 This is indicated by an underscore prefix on the field names. 191 192 All other PyInterpreterState pointer fields are populated when 193 needed and default to NULL. 194 */ 195 // Note some fields do not have a leading underscore for backward 196 // compatibility. See https://bugs.python.org/issue45953#msg412046. 197 198 /* The thread's exception stack entry. (Always the last entry.) */ 199 _PyErr_StackItem exc_state; 200 201 /* The bottom-most frame on the stack. */ 202 _PyCFrame root_cframe; 203 }; 204 205 206 /* other API */ 207 208 // Alias for backward compatibility with Python 3.8 209 #define _PyInterpreterState_Get PyInterpreterState_Get 210 211 PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *); 212 213 /* Similar to PyThreadState_Get(), but don't issue a fatal error 214 * if it is NULL. */ 215 PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void); 216 217 PyAPI_FUNC(PyObject *) _PyThreadState_GetDict(PyThreadState *tstate); 218 219 // Disable tracing and profiling. 220 PyAPI_FUNC(void) PyThreadState_EnterTracing(PyThreadState *tstate); 221 222 // Reset tracing and profiling: enable them if a trace function or a profile 223 // function is set, otherwise disable them. 224 PyAPI_FUNC(void) PyThreadState_LeaveTracing(PyThreadState *tstate); 225 226 /* PyGILState */ 227 228 /* Helper/diagnostic function - return 1 if the current thread 229 currently holds the GIL, 0 otherwise. 230 231 The function returns 1 if _PyGILState_check_enabled is non-zero. */ 232 PyAPI_FUNC(int) PyGILState_Check(void); 233 234 /* Get the single PyInterpreterState used by this process' GILState 235 implementation. 236 237 This function doesn't check for error. Return NULL before _PyGILState_Init() 238 is called and after _PyGILState_Fini() is called. 239 240 See also _PyInterpreterState_Get() and _PyInterpreterState_GET(). */ 241 PyAPI_FUNC(PyInterpreterState *) _PyGILState_GetInterpreterStateUnsafe(void); 242 243 /* The implementation of sys._current_frames() Returns a dict mapping 244 thread id to that thread's current frame. 245 */ 246 PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void); 247 248 /* The implementation of sys._current_exceptions() Returns a dict mapping 249 thread id to that thread's current exception. 250 */ 251 PyAPI_FUNC(PyObject *) _PyThread_CurrentExceptions(void); 252 253 /* Routines for advanced debuggers, requested by David Beazley. 254 Don't use unless you know what you are doing! */ 255 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void); 256 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void); 257 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *); 258 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *); 259 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *); 260 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void); 261 262 /* Frame evaluation API */ 263 264 typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int); 265 266 PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc( 267 PyInterpreterState *interp); 268 PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc( 269 PyInterpreterState *interp, 270 _PyFrameEvalFunction eval_frame); 271 272 PyAPI_FUNC(const PyConfig*) _PyInterpreterState_GetConfig(PyInterpreterState *interp); 273 274 /* Get a copy of the current interpreter configuration. 275 276 Return 0 on success. Raise an exception and return -1 on error. 277 278 The caller must initialize 'config', using PyConfig_InitPythonConfig() 279 for example. 280 281 Python must be preinitialized to call this method. 282 The caller must hold the GIL. */ 283 PyAPI_FUNC(int) _PyInterpreterState_GetConfigCopy( 284 struct PyConfig *config); 285 286 /* Set the configuration of the current interpreter. 287 288 This function should be called during or just after the Python 289 initialization. 290 291 Update the sys module with the new configuration. If the sys module was 292 modified directly after the Python initialization, these changes are lost. 293 294 Some configuration like faulthandler or warnoptions can be updated in the 295 configuration, but don't reconfigure Python (don't enable/disable 296 faulthandler and don't reconfigure warnings filters). 297 298 Return 0 on success. Raise an exception and return -1 on error. 299 300 The configuration should come from _PyInterpreterState_GetConfigCopy(). */ 301 PyAPI_FUNC(int) _PyInterpreterState_SetConfig( 302 const struct PyConfig *config); 303 304 // Get the configuration of the current interpreter. 305 // The caller must hold the GIL. 306 PyAPI_FUNC(const PyConfig*) _Py_GetConfig(void); 307 308 309 /* cross-interpreter data */ 310 311 // _PyCrossInterpreterData is similar to Py_buffer as an effectively 312 // opaque struct that holds data outside the object machinery. This 313 // is necessary to pass safely between interpreters in the same process. 314 typedef struct _xid _PyCrossInterpreterData; 315 316 struct _xid { 317 // data is the cross-interpreter-safe derivation of a Python object 318 // (see _PyObject_GetCrossInterpreterData). It will be NULL if the 319 // new_object func (below) encodes the data. 320 void *data; 321 // obj is the Python object from which the data was derived. This 322 // is non-NULL only if the data remains bound to the object in some 323 // way, such that the object must be "released" (via a decref) when 324 // the data is released. In that case the code that sets the field, 325 // likely a registered "crossinterpdatafunc", is responsible for 326 // ensuring it owns the reference (i.e. incref). 327 PyObject *obj; 328 // interp is the ID of the owning interpreter of the original 329 // object. It corresponds to the active interpreter when 330 // _PyObject_GetCrossInterpreterData() was called. This should only 331 // be set by the cross-interpreter machinery. 332 // 333 // We use the ID rather than the PyInterpreterState to avoid issues 334 // with deleted interpreters. Note that IDs are never re-used, so 335 // each one will always correspond to a specific interpreter 336 // (whether still alive or not). 337 int64_t interp; 338 // new_object is a function that returns a new object in the current 339 // interpreter given the data. The resulting object (a new 340 // reference) will be equivalent to the original object. This field 341 // is required. 342 PyObject *(*new_object)(_PyCrossInterpreterData *); 343 // free is called when the data is released. If it is NULL then 344 // nothing will be done to free the data. For some types this is 345 // okay (e.g. bytes) and for those types this field should be set 346 // to NULL. However, for most the data was allocated just for 347 // cross-interpreter use, so it must be freed when 348 // _PyCrossInterpreterData_Release is called or the memory will 349 // leak. In that case, at the very least this field should be set 350 // to PyMem_RawFree (the default if not explicitly set to NULL). 351 // The call will happen with the original interpreter activated. 352 void (*free)(void *); 353 }; 354 355 PyAPI_FUNC(int) _PyObject_GetCrossInterpreterData(PyObject *, _PyCrossInterpreterData *); 356 PyAPI_FUNC(PyObject *) _PyCrossInterpreterData_NewObject(_PyCrossInterpreterData *); 357 PyAPI_FUNC(void) _PyCrossInterpreterData_Release(_PyCrossInterpreterData *); 358 359 PyAPI_FUNC(int) _PyObject_CheckCrossInterpreterData(PyObject *); 360 361 /* cross-interpreter data registry */ 362 363 typedef int (*crossinterpdatafunc)(PyObject *, _PyCrossInterpreterData *); 364 365 PyAPI_FUNC(int) _PyCrossInterpreterData_RegisterClass(PyTypeObject *, crossinterpdatafunc); 366 PyAPI_FUNC(crossinterpdatafunc) _PyCrossInterpreterData_Lookup(PyObject *); 367