1#ifndef Py_CPYTHON_PYSTATE_H
2#  error "this header file must not be included directly"
3#endif
4
5
6PyAPI_FUNC(int) _PyInterpreterState_RequiresIDRef(PyInterpreterState *);
7PyAPI_FUNC(void) _PyInterpreterState_RequireIDRef(PyInterpreterState *, int);
8
9PyAPI_FUNC(PyObject *) _PyInterpreterState_GetMainModule(PyInterpreterState *);
10
11/* State unique per thread */
12
13/* Py_tracefunc return -1 when raising an exception, or 0 for success. */
14typedef int (*Py_tracefunc)(PyObject *, PyFrameObject *, int, PyObject *);
15
16/* The following values are used for 'what' for tracefunc functions
17 *
18 * To add a new kind of trace event, also update "trace_init" in
19 * Python/sysmodule.c to define the Python level event name
20 */
21#define PyTrace_CALL 0
22#define PyTrace_EXCEPTION 1
23#define PyTrace_LINE 2
24#define PyTrace_RETURN 3
25#define PyTrace_C_CALL 4
26#define PyTrace_C_EXCEPTION 5
27#define PyTrace_C_RETURN 6
28#define PyTrace_OPCODE 7
29
30
31typedef struct {
32    PyCodeObject *code; // The code object for the bounds. May be NULL.
33    PyCodeAddressRange bounds; // Only valid if code != NULL.
34} PyTraceInfo;
35
36// Internal structure: you should not use it directly, but use public functions
37// like PyThreadState_EnterTracing() and PyThreadState_LeaveTracing().
38typedef struct _PyCFrame {
39    /* This struct will be threaded through the C stack
40     * allowing fast access to per-thread state that needs
41     * to be accessed quickly by the interpreter, but can
42     * be modified outside of the interpreter.
43     *
44     * WARNING: This makes data on the C stack accessible from
45     * heap objects. Care must be taken to maintain stack
46     * discipline and make sure that instances of this struct cannot
47     * accessed outside of their lifetime.
48     */
49    uint8_t use_tracing;  // 0 or 255 (or'ed into opcode, hence 8-bit type)
50    /* Pointer to the currently executing frame (it can be NULL) */
51    struct _PyInterpreterFrame *current_frame;
52    struct _PyCFrame *previous;
53} _PyCFrame;
54
55typedef struct _err_stackitem {
56    /* This struct represents a single execution context where we might
57     * be currently handling an exception.  It is a per-coroutine state
58     * (coroutine in the computer science sense, including the thread
59     * and generators).
60     *
61     * This is used as an entry on the exception stack, where each
62     * entry indicates if it is currently handling an exception.
63     * This ensures that the exception state is not impacted
64     * by "yields" from an except handler.  The thread
65     * always has an entry (the bottom-most one).
66     */
67
68    /* The exception currently being handled in this context, if any. */
69    PyObject *exc_value;
70
71    struct _err_stackitem *previous_item;
72
73} _PyErr_StackItem;
74
75typedef struct _stack_chunk {
76    struct _stack_chunk *previous;
77    size_t size;
78    size_t top;
79    PyObject * data[1]; /* Variable sized */
80} _PyStackChunk;
81
82struct _ts {
83    /* See Python/ceval.c for comments explaining most fields */
84
85    PyThreadState *prev;
86    PyThreadState *next;
87    PyInterpreterState *interp;
88
89    /* Has been initialized to a safe state.
90
91       In order to be effective, this must be set to 0 during or right
92       after allocation. */
93    int _initialized;
94
95    /* Was this thread state statically allocated? */
96    int _static;
97
98    int recursion_remaining;
99    int recursion_limit;
100    int recursion_headroom; /* Allow 50 more calls to handle any errors. */
101
102    /* 'tracing' keeps track of the execution depth when tracing/profiling.
103       This is to prevent the actual trace/profile code from being recorded in
104       the trace/profile. */
105    int tracing;
106    int tracing_what; /* The event currently being traced, if any. */
107
108    /* Pointer to current _PyCFrame in the C stack frame of the currently,
109     * or most recently, executing _PyEval_EvalFrameDefault. */
110    _PyCFrame *cframe;
111
112    Py_tracefunc c_profilefunc;
113    Py_tracefunc c_tracefunc;
114    PyObject *c_profileobj;
115    PyObject *c_traceobj;
116
117    /* The exception currently being raised */
118    PyObject *curexc_type;
119    PyObject *curexc_value;
120    PyObject *curexc_traceback;
121
122    /* Pointer to the top of the exception stack for the exceptions
123     * we may be currently handling.  (See _PyErr_StackItem above.)
124     * This is never NULL. */
125    _PyErr_StackItem *exc_info;
126
127    PyObject *dict;  /* Stores per-thread state */
128
129    int gilstate_counter;
130
131    PyObject *async_exc; /* Asynchronous exception to raise */
132    unsigned long thread_id; /* Thread id where this tstate was created */
133
134    /* Native thread id where this tstate was created. This will be 0 except on
135     * those platforms that have the notion of native thread id, for which the
136     * macro PY_HAVE_THREAD_NATIVE_ID is then defined.
137     */
138    unsigned long native_thread_id;
139
140    int trash_delete_nesting;
141    PyObject *trash_delete_later;
142
143    /* Called when a thread state is deleted normally, but not when it
144     * is destroyed after fork().
145     * Pain:  to prevent rare but fatal shutdown errors (issue 18808),
146     * Thread.join() must wait for the join'ed thread's tstate to be unlinked
147     * from the tstate chain.  That happens at the end of a thread's life,
148     * in pystate.c.
149     * The obvious way doesn't quite work:  create a lock which the tstate
150     * unlinking code releases, and have Thread.join() wait to acquire that
151     * lock.  The problem is that we _are_ at the end of the thread's life:
152     * if the thread holds the last reference to the lock, decref'ing the
153     * lock will delete the lock, and that may trigger arbitrary Python code
154     * if there's a weakref, with a callback, to the lock.  But by this time
155     * _PyRuntime.gilstate.tstate_current is already NULL, so only the simplest
156     * of C code can be allowed to run (in particular it must not be possible to
157     * release the GIL).
158     * So instead of holding the lock directly, the tstate holds a weakref to
159     * the lock:  that's the value of on_delete_data below.  Decref'ing a
160     * weakref is harmless.
161     * on_delete points to _threadmodule.c's static release_sentinel() function.
162     * After the tstate is unlinked, release_sentinel is called with the
163     * weakref-to-lock (on_delete_data) argument, and release_sentinel releases
164     * the indirectly held lock.
165     */
166    void (*on_delete)(void *);
167    void *on_delete_data;
168
169    int coroutine_origin_tracking_depth;
170
171    PyObject *async_gen_firstiter;
172    PyObject *async_gen_finalizer;
173
174    PyObject *context;
175    uint64_t context_ver;
176
177    /* Unique thread state id. */
178    uint64_t id;
179
180    PyTraceInfo trace_info;
181
182    _PyStackChunk *datastack_chunk;
183    PyObject **datastack_top;
184    PyObject **datastack_limit;
185    /* XXX signal handlers should also be here */
186
187    /* The following fields are here to avoid allocation during init.
188       The data is exposed through PyThreadState pointer fields.
189       These fields should not be accessed directly outside of init.
190       This is indicated by an underscore prefix on the field names.
191
192       All other PyInterpreterState pointer fields are populated when
193       needed and default to NULL.
194       */
195       // Note some fields do not have a leading underscore for backward
196       // compatibility.  See https://bugs.python.org/issue45953#msg412046.
197
198    /* The thread's exception stack entry.  (Always the last entry.) */
199    _PyErr_StackItem exc_state;
200
201    /* The bottom-most frame on the stack. */
202    _PyCFrame root_cframe;
203};
204
205
206/* other API */
207
208// Alias for backward compatibility with Python 3.8
209#define _PyInterpreterState_Get PyInterpreterState_Get
210
211PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *);
212
213/* Similar to PyThreadState_Get(), but don't issue a fatal error
214 * if it is NULL. */
215PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void);
216
217PyAPI_FUNC(PyObject *) _PyThreadState_GetDict(PyThreadState *tstate);
218
219// Disable tracing and profiling.
220PyAPI_FUNC(void) PyThreadState_EnterTracing(PyThreadState *tstate);
221
222// Reset tracing and profiling: enable them if a trace function or a profile
223// function is set, otherwise disable them.
224PyAPI_FUNC(void) PyThreadState_LeaveTracing(PyThreadState *tstate);
225
226/* PyGILState */
227
228/* Helper/diagnostic function - return 1 if the current thread
229   currently holds the GIL, 0 otherwise.
230
231   The function returns 1 if _PyGILState_check_enabled is non-zero. */
232PyAPI_FUNC(int) PyGILState_Check(void);
233
234/* Get the single PyInterpreterState used by this process' GILState
235   implementation.
236
237   This function doesn't check for error. Return NULL before _PyGILState_Init()
238   is called and after _PyGILState_Fini() is called.
239
240   See also _PyInterpreterState_Get() and _PyInterpreterState_GET(). */
241PyAPI_FUNC(PyInterpreterState *) _PyGILState_GetInterpreterStateUnsafe(void);
242
243/* The implementation of sys._current_frames()  Returns a dict mapping
244   thread id to that thread's current frame.
245*/
246PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void);
247
248/* The implementation of sys._current_exceptions()  Returns a dict mapping
249   thread id to that thread's current exception.
250*/
251PyAPI_FUNC(PyObject *) _PyThread_CurrentExceptions(void);
252
253/* Routines for advanced debuggers, requested by David Beazley.
254   Don't use unless you know what you are doing! */
255PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void);
256PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
257PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
258PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
259PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
260PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
261
262/* Frame evaluation API */
263
264typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
265
266PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
267    PyInterpreterState *interp);
268PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
269    PyInterpreterState *interp,
270    _PyFrameEvalFunction eval_frame);
271
272PyAPI_FUNC(const PyConfig*) _PyInterpreterState_GetConfig(PyInterpreterState *interp);
273
274/* Get a copy of the current interpreter configuration.
275
276   Return 0 on success. Raise an exception and return -1 on error.
277
278   The caller must initialize 'config', using PyConfig_InitPythonConfig()
279   for example.
280
281   Python must be preinitialized to call this method.
282   The caller must hold the GIL. */
283PyAPI_FUNC(int) _PyInterpreterState_GetConfigCopy(
284    struct PyConfig *config);
285
286/* Set the configuration of the current interpreter.
287
288   This function should be called during or just after the Python
289   initialization.
290
291   Update the sys module with the new configuration. If the sys module was
292   modified directly after the Python initialization, these changes are lost.
293
294   Some configuration like faulthandler or warnoptions can be updated in the
295   configuration, but don't reconfigure Python (don't enable/disable
296   faulthandler and don't reconfigure warnings filters).
297
298   Return 0 on success. Raise an exception and return -1 on error.
299
300   The configuration should come from _PyInterpreterState_GetConfigCopy(). */
301PyAPI_FUNC(int) _PyInterpreterState_SetConfig(
302    const struct PyConfig *config);
303
304// Get the configuration of the current interpreter.
305// The caller must hold the GIL.
306PyAPI_FUNC(const PyConfig*) _Py_GetConfig(void);
307
308
309/* cross-interpreter data */
310
311// _PyCrossInterpreterData is similar to Py_buffer as an effectively
312// opaque struct that holds data outside the object machinery.  This
313// is necessary to pass safely between interpreters in the same process.
314typedef struct _xid _PyCrossInterpreterData;
315
316struct _xid {
317    // data is the cross-interpreter-safe derivation of a Python object
318    // (see _PyObject_GetCrossInterpreterData).  It will be NULL if the
319    // new_object func (below) encodes the data.
320    void *data;
321    // obj is the Python object from which the data was derived.  This
322    // is non-NULL only if the data remains bound to the object in some
323    // way, such that the object must be "released" (via a decref) when
324    // the data is released.  In that case the code that sets the field,
325    // likely a registered "crossinterpdatafunc", is responsible for
326    // ensuring it owns the reference (i.e. incref).
327    PyObject *obj;
328    // interp is the ID of the owning interpreter of the original
329    // object.  It corresponds to the active interpreter when
330    // _PyObject_GetCrossInterpreterData() was called.  This should only
331    // be set by the cross-interpreter machinery.
332    //
333    // We use the ID rather than the PyInterpreterState to avoid issues
334    // with deleted interpreters.  Note that IDs are never re-used, so
335    // each one will always correspond to a specific interpreter
336    // (whether still alive or not).
337    int64_t interp;
338    // new_object is a function that returns a new object in the current
339    // interpreter given the data.  The resulting object (a new
340    // reference) will be equivalent to the original object.  This field
341    // is required.
342    PyObject *(*new_object)(_PyCrossInterpreterData *);
343    // free is called when the data is released.  If it is NULL then
344    // nothing will be done to free the data.  For some types this is
345    // okay (e.g. bytes) and for those types this field should be set
346    // to NULL.  However, for most the data was allocated just for
347    // cross-interpreter use, so it must be freed when
348    // _PyCrossInterpreterData_Release is called or the memory will
349    // leak.  In that case, at the very least this field should be set
350    // to PyMem_RawFree (the default if not explicitly set to NULL).
351    // The call will happen with the original interpreter activated.
352    void (*free)(void *);
353};
354
355PyAPI_FUNC(int) _PyObject_GetCrossInterpreterData(PyObject *, _PyCrossInterpreterData *);
356PyAPI_FUNC(PyObject *) _PyCrossInterpreterData_NewObject(_PyCrossInterpreterData *);
357PyAPI_FUNC(void) _PyCrossInterpreterData_Release(_PyCrossInterpreterData *);
358
359PyAPI_FUNC(int) _PyObject_CheckCrossInterpreterData(PyObject *);
360
361/* cross-interpreter data registry */
362
363typedef int (*crossinterpdatafunc)(PyObject *, _PyCrossInterpreterData *);
364
365PyAPI_FUNC(int) _PyCrossInterpreterData_RegisterClass(PyTypeObject *, crossinterpdatafunc);
366PyAPI_FUNC(crossinterpdatafunc) _PyCrossInterpreterData_Lookup(PyObject *);
367