Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/python3.8/cpython/pystate.h @ 69:33d812a61356

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