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