1#ifndef Py_CPYTHON_PYSTATE_H
2# error "this header file must not be included directly"
3#endif
4
5PyAPI_FUNC(int) _PyInterpreterState_RequiresIDRef(PyInterpreterState *);
6PyAPI_FUNC(void) _PyInterpreterState_RequireIDRef(PyInterpreterState *, int);
7
8PyAPI_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. */
13typedef 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
30typedef 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
45typedef 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.
60struct _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
157PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *);
158
159/* Similar to PyThreadState_Get(), but don't issue a fatal error
160 * if it is NULL. */
161PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void);
162
163PyAPI_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. */
171PyAPI_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(). */
180PyAPI_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*/
185PyAPI_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*/
190PyAPI_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! */
194PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void);
195PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
196PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
197PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
198PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
199PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
200
201/* Frame evaluation API */
202
203typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, PyFrameObject *, int);
204
205PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
206 PyInterpreterState *interp);
207PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
208 PyInterpreterState *interp,
209 _PyFrameEvalFunction eval_frame);
210
211PyAPI_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. */
222PyAPI_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(). */
240PyAPI_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.
245PyAPI_FUNC(const PyConfig*) _Py_GetConfig(void);
246
247
248/* cross-interpreter data */
249
250struct _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.
255typedef 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
294PyAPI_FUNC(int) _PyObject_GetCrossInterpreterData(PyObject *, _PyCrossInterpreterData *);
295PyAPI_FUNC(PyObject *) _PyCrossInterpreterData_NewObject(_PyCrossInterpreterData *);
296PyAPI_FUNC(void) _PyCrossInterpreterData_Release(_PyCrossInterpreterData *);
297
298PyAPI_FUNC(int) _PyObject_CheckCrossInterpreterData(PyObject *);
299
300/* cross-interpreter data registry */
301
302typedef int (*crossinterpdatafunc)(PyObject *, struct _xid *);
303
304PyAPI_FUNC(int) _PyCrossInterpreterData_RegisterClass(PyTypeObject *, crossinterpdatafunc);
305PyAPI_FUNC(crossinterpdatafunc) _PyCrossInterpreterData_Lookup(PyObject *);
306

source code of include/python3.10/cpython/pystate.h