1 #ifndef Py_CPYTHON_PYSTATE_H
2 # error "this header file must not be included directly"
3 #endif
4
5
6 PyAPI_FUNC(int) _PyInterpreterState_RequiresIDRef(PyInterpreterState *);
7 PyAPI_FUNC(void) _PyInterpreterState_RequireIDRef(PyInterpreterState *, int);
8
9 PyAPI_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. */
14 typedef 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
31 typedef 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().
38 typedef 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
55 typedef 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
75 typedef 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
82 struct _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
211 PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *);
212
213 /* Similar to PyThreadState_Get(), but don't issue a fatal error
214 * if it is NULL. */
215 PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void);
216
217 PyAPI_FUNC(PyObject *) _PyThreadState_GetDict(PyThreadState *tstate);
218
219 // Disable tracing and profiling.
220 PyAPI_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.
224 PyAPI_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. */
232 PyAPI_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(). */
241 PyAPI_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 */
246 PyAPI_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 */
251 PyAPI_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! */
255 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void);
256 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
257 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
258 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
259 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
260 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
261
262 /* Frame evaluation API */
263
264 typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
265
266 PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
267 PyInterpreterState *interp);
268 PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
269 PyInterpreterState *interp,
270 _PyFrameEvalFunction eval_frame);
271
272 PyAPI_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. */
283 PyAPI_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(). */
301 PyAPI_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.
306 PyAPI_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.
314 typedef struct _xid _PyCrossInterpreterData;
315
316 struct _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
355 PyAPI_FUNC(int) _PyObject_GetCrossInterpreterData(PyObject *, _PyCrossInterpreterData *);
356 PyAPI_FUNC(PyObject *) _PyCrossInterpreterData_NewObject(_PyCrossInterpreterData *);
357 PyAPI_FUNC(void) _PyCrossInterpreterData_Release(_PyCrossInterpreterData *);
358
359 PyAPI_FUNC(int) _PyObject_CheckCrossInterpreterData(PyObject *);
360
361 /* cross-interpreter data registry */
362
363 typedef int (*crossinterpdatafunc)(PyObject *, _PyCrossInterpreterData *);
364
365 PyAPI_FUNC(int) _PyCrossInterpreterData_RegisterClass(PyTypeObject *, crossinterpdatafunc);
366 PyAPI_FUNC(crossinterpdatafunc) _PyCrossInterpreterData_Lookup(PyObject *);