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