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