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 *, struct _frame *, 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 struct _frame *frame; 59 int recursion_depth; 60 char overflowed; /* The stack has overflowed. Allow 50 more calls 61 to handle the runtime error. */ 62 char recursion_critical; /* The current calls must not cause 63 a stack overflow. */ 64 int stackcheck_counter; 65 66 /* 'tracing' keeps track of the execution depth when tracing/profiling. 67 This is to prevent the actual trace/profile code from being recorded in 68 the trace/profile. */ 69 int tracing; 70 int use_tracing; 71 72 Py_tracefunc c_profilefunc; 73 Py_tracefunc c_tracefunc; 74 PyObject *c_profileobj; 75 PyObject *c_traceobj; 76 77 /* The exception currently being raised */ 78 PyObject *curexc_type; 79 PyObject *curexc_value; 80 PyObject *curexc_traceback; 81 82 /* The exception currently being handled, if no coroutines/generators 83 * are present. Always last element on the stack referred to be exc_info. 84 */ 85 _PyErr_StackItem exc_state; 86 87 /* Pointer to the top of the stack of the exceptions currently 88 * being handled */ 89 _PyErr_StackItem *exc_info; 90 91 PyObject *dict; /* Stores per-thread state */ 92 93 int gilstate_counter; 94 95 PyObject *async_exc; /* Asynchronous exception to raise */ 96 unsigned long thread_id; /* Thread id where this tstate was created */ 97 98 int trash_delete_nesting; 99 PyObject *trash_delete_later; 100 101 /* Called when a thread state is deleted normally, but not when it 102 * is destroyed after fork(). 103 * Pain: to prevent rare but fatal shutdown errors (issue 18808), 104 * Thread.join() must wait for the join'ed thread's tstate to be unlinked 105 * from the tstate chain. That happens at the end of a thread's life, 106 * in pystate.c. 107 * The obvious way doesn't quite work: create a lock which the tstate 108 * unlinking code releases, and have Thread.join() wait to acquire that 109 * lock. The problem is that we _are_ at the end of the thread's life: 110 * if the thread holds the last reference to the lock, decref'ing the 111 * lock will delete the lock, and that may trigger arbitrary Python code 112 * if there's a weakref, with a callback, to the lock. But by this time 113 * _PyRuntime.gilstate.tstate_current is already NULL, so only the simplest 114 * of C code can be allowed to run (in particular it must not be possible to 115 * release the GIL). 116 * So instead of holding the lock directly, the tstate holds a weakref to 117 * the lock: that's the value of on_delete_data below. Decref'ing a 118 * weakref is harmless. 119 * on_delete points to _threadmodule.c's static release_sentinel() function. 120 * After the tstate is unlinked, release_sentinel is called with the 121 * weakref-to-lock (on_delete_data) argument, and release_sentinel releases 122 * the indirectly held lock. 123 */ 124 void (*on_delete)(void *); 125 void *on_delete_data; 126 127 int coroutine_origin_tracking_depth; 128 129 PyObject *async_gen_firstiter; 130 PyObject *async_gen_finalizer; 131 132 PyObject *context; 133 uint64_t context_ver; 134 135 /* Unique thread state id. */ 136 uint64_t id; 137 138 /* XXX signal handlers should also be here */ 139 140 }; 141 142 /* Get the current interpreter state. 143 144 Issue a fatal error if there no current Python thread state or no current 145 interpreter. It cannot return NULL. 146 147 The caller must hold the GIL.*/ 148 PyAPI_FUNC(PyInterpreterState *) _PyInterpreterState_Get(void); 149 150 PyAPI_FUNC(int) _PyState_AddModule(PyObject*, struct PyModuleDef*); 151 PyAPI_FUNC(void) _PyState_ClearModules(void); 152 PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *); 153 154 /* Similar to PyThreadState_Get(), but don't issue a fatal error 155 * if it is NULL. */ 156 PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void); 157 158 /* PyGILState */ 159 160 /* Helper/diagnostic function - return 1 if the current thread 161 currently holds the GIL, 0 otherwise. 162 163 The function returns 1 if _PyGILState_check_enabled is non-zero. */ 164 PyAPI_FUNC(int) PyGILState_Check(void); 165 166 /* Get the single PyInterpreterState used by this process' GILState 167 implementation. 168 169 This function doesn't check for error. Return NULL before _PyGILState_Init() 170 is called and after _PyGILState_Fini() is called. 171 172 See also _PyInterpreterState_Get() and _PyInterpreterState_GET_UNSAFE(). */ 173 PyAPI_FUNC(PyInterpreterState *) _PyGILState_GetInterpreterStateUnsafe(void); 174 175 /* The implementation of sys._current_frames() Returns a dict mapping 176 thread id to that thread's current frame. 177 */ 178 PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void); 179 180 /* Routines for advanced debuggers, requested by David Beazley. 181 Don't use unless you know what you are doing! */ 182 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void); 183 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void); 184 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *); 185 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *); 186 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *); 187 188 typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_); 189 190 /* cross-interpreter data */ 191 192 struct _xid; 193 194 // _PyCrossInterpreterData is similar to Py_buffer as an effectively 195 // opaque struct that holds data outside the object machinery. This 196 // is necessary to pass safely between interpreters in the same process. 197 typedef struct _xid { 198 // data is the cross-interpreter-safe derivation of a Python object 199 // (see _PyObject_GetCrossInterpreterData). It will be NULL if the 200 // new_object func (below) encodes the data. 201 void *data; 202 // obj is the Python object from which the data was derived. This 203 // is non-NULL only if the data remains bound to the object in some 204 // way, such that the object must be "released" (via a decref) when 205 // the data is released. In that case the code that sets the field, 206 // likely a registered "crossinterpdatafunc", is responsible for 207 // ensuring it owns the reference (i.e. incref). 208 PyObject *obj; 209 // interp is the ID of the owning interpreter of the original 210 // object. It corresponds to the active interpreter when 211 // _PyObject_GetCrossInterpreterData() was called. This should only 212 // be set by the cross-interpreter machinery. 213 // 214 // We use the ID rather than the PyInterpreterState to avoid issues 215 // with deleted interpreters. Note that IDs are never re-used, so 216 // each one will always correspond to a specific interpreter 217 // (whether still alive or not). 218 int64_t interp; 219 // new_object is a function that returns a new object in the current 220 // interpreter given the data. The resulting object (a new 221 // reference) will be equivalent to the original object. This field 222 // is required. 223 PyObject *(*new_object)(struct _xid *); 224 // free is called when the data is released. If it is NULL then 225 // nothing will be done to free the data. For some types this is 226 // okay (e.g. bytes) and for those types this field should be set 227 // to NULL. However, for most the data was allocated just for 228 // cross-interpreter use, so it must be freed when 229 // _PyCrossInterpreterData_Release is called or the memory will 230 // leak. In that case, at the very least this field should be set 231 // to PyMem_RawFree (the default if not explicitly set to NULL). 232 // The call will happen with the original interpreter activated. 233 void (*free)(void *); 234 } _PyCrossInterpreterData; 235 236 PyAPI_FUNC(int) _PyObject_GetCrossInterpreterData(PyObject *, _PyCrossInterpreterData *); 237 PyAPI_FUNC(PyObject *) _PyCrossInterpreterData_NewObject(_PyCrossInterpreterData *); 238 PyAPI_FUNC(void) _PyCrossInterpreterData_Release(_PyCrossInterpreterData *); 239 240 PyAPI_FUNC(int) _PyObject_CheckCrossInterpreterData(PyObject *); 241 242 /* cross-interpreter data registry */ 243 244 typedef int (*crossinterpdatafunc)(PyObject *, struct _xid *); 245 246 PyAPI_FUNC(int) _PyCrossInterpreterData_RegisterClass(PyTypeObject *, crossinterpdatafunc); 247 PyAPI_FUNC(crossinterpdatafunc) _PyCrossInterpreterData_Lookup(PyObject *); 248 249 #ifdef __cplusplus 250 } 251 #endif 252