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 /* Borrowed reference to the current frame (it can be NULL) */ 59 struct _frame *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 /* Get the current interpreter state. 144 145 Issue a fatal error if there no current Python thread state or no current 146 interpreter. It cannot return NULL. 147 148 The caller must hold the GIL.*/ 149 PyAPI_FUNC(PyInterpreterState *) _PyInterpreterState_Get(void); 150 151 PyAPI_FUNC(int) _PyState_AddModule(PyObject*, struct PyModuleDef*); 152 PyAPI_FUNC(void) _PyState_ClearModules(void); 153 PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *); 154 155 /* Similar to PyThreadState_Get(), but don't issue a fatal error 156 * if it is NULL. */ 157 PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void); 158 159 /* PyGILState */ 160 161 /* Helper/diagnostic function - return 1 if the current thread 162 currently holds the GIL, 0 otherwise. 163 164 The function returns 1 if _PyGILState_check_enabled is non-zero. */ 165 PyAPI_FUNC(int) PyGILState_Check(void); 166 167 /* Get the single PyInterpreterState used by this process' GILState 168 implementation. 169 170 This function doesn't check for error. Return NULL before _PyGILState_Init() 171 is called and after _PyGILState_Fini() is called. 172 173 See also _PyInterpreterState_Get() and _PyInterpreterState_GET_UNSAFE(). */ 174 PyAPI_FUNC(PyInterpreterState *) _PyGILState_GetInterpreterStateUnsafe(void); 175 176 /* The implementation of sys._current_frames() Returns a dict mapping 177 thread id to that thread's current frame. 178 */ 179 PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void); 180 181 /* Routines for advanced debuggers, requested by David Beazley. 182 Don't use unless you know what you are doing! */ 183 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void); 184 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void); 185 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *); 186 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *); 187 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *); 188 189 typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_); 190 191 /* cross-interpreter data */ 192 193 struct _xid; 194 195 // _PyCrossInterpreterData is similar to Py_buffer as an effectively 196 // opaque struct that holds data outside the object machinery. This 197 // is necessary to pass safely between interpreters in the same process. 198 typedef struct _xid { 199 // data is the cross-interpreter-safe derivation of a Python object 200 // (see _PyObject_GetCrossInterpreterData). It will be NULL if the 201 // new_object func (below) encodes the data. 202 void *data; 203 // obj is the Python object from which the data was derived. This 204 // is non-NULL only if the data remains bound to the object in some 205 // way, such that the object must be "released" (via a decref) when 206 // the data is released. In that case the code that sets the field, 207 // likely a registered "crossinterpdatafunc", is responsible for 208 // ensuring it owns the reference (i.e. incref). 209 PyObject *obj; 210 // interp is the ID of the owning interpreter of the original 211 // object. It corresponds to the active interpreter when 212 // _PyObject_GetCrossInterpreterData() was called. This should only 213 // be set by the cross-interpreter machinery. 214 // 215 // We use the ID rather than the PyInterpreterState to avoid issues 216 // with deleted interpreters. Note that IDs are never re-used, so 217 // each one will always correspond to a specific interpreter 218 // (whether still alive or not). 219 int64_t interp; 220 // new_object is a function that returns a new object in the current 221 // interpreter given the data. The resulting object (a new 222 // reference) will be equivalent to the original object. This field 223 // is required. 224 PyObject *(*new_object)(struct _xid *); 225 // free is called when the data is released. If it is NULL then 226 // nothing will be done to free the data. For some types this is 227 // okay (e.g. bytes) and for those types this field should be set 228 // to NULL. However, for most the data was allocated just for 229 // cross-interpreter use, so it must be freed when 230 // _PyCrossInterpreterData_Release is called or the memory will 231 // leak. In that case, at the very least this field should be set 232 // to PyMem_RawFree (the default if not explicitly set to NULL). 233 // The call will happen with the original interpreter activated. 234 void (*free)(void *); 235 } _PyCrossInterpreterData; 236 237 PyAPI_FUNC(int) _PyObject_GetCrossInterpreterData(PyObject *, _PyCrossInterpreterData *); 238 PyAPI_FUNC(PyObject *) _PyCrossInterpreterData_NewObject(_PyCrossInterpreterData *); 239 PyAPI_FUNC(void) _PyCrossInterpreterData_Release(_PyCrossInterpreterData *); 240 241 PyAPI_FUNC(int) _PyObject_CheckCrossInterpreterData(PyObject *); 242 243 /* cross-interpreter data registry */ 244 245 typedef int (*crossinterpdatafunc)(PyObject *, struct _xid *); 246 247 PyAPI_FUNC(int) _PyCrossInterpreterData_RegisterClass(PyTypeObject *, crossinterpdatafunc); 248 PyAPI_FUNC(crossinterpdatafunc) _PyCrossInterpreterData_Lookup(PyObject *); 249 250 #ifdef __cplusplus 251 } 252 #endif 253