Debian Codegraph @

Include/cpython/pystate.h

raw
1 #ifndef Py_CPYTHON_PYSTATE_H
2 # error "this header file must not be included directly"
3 #endif
4
5
6 /* private interpreter helpers */
7
8 PyAPI_FUNC(int) _PyInterpreterState_RequiresIDRef(PyInterpreterState *);
9 PyAPI_FUNC(void) _PyInterpreterState_RequireIDRef(PyInterpreterState *, int);
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 /* Remote debugger support */
31 #define _Py_MAX_SCRIPT_PATH_SIZE 512
32 typedef struct {
33 int32_t debugger_pending_call;
34 char debugger_script_path[_Py_MAX_SCRIPT_PATH_SIZE];
35 } _PyRemoteDebuggerSupport;
36
37 typedef struct _err_stackitem {
38 /* This struct represents a single execution context where we might
39 * be currently handling an exception. It is a per-coroutine state
40 * (coroutine in the computer science sense, including the thread
41 * and generators).
42 *
43 * This is used as an entry on the exception stack, where each
44 * entry indicates if it is currently handling an exception.
45 * This ensures that the exception state is not impacted
46 * by "yields" from an except handler. The thread
47 * always has an entry (the bottom-most one).
48 */
49
50 /* The exception currently being handled in this context, if any. */
51 PyObject *exc_value;
52
53 struct _err_stackitem *previous_item;
54
55 } _PyErr_StackItem;
56
57 typedef struct _stack_chunk {
58 struct _stack_chunk *previous;
59 size_t size;
60 size_t top;
61 PyObject * data[1]; /* Variable sized */
62 } _PyStackChunk;
63
64 /* Minimum size of data stack chunk */
65 #define _PY_DATA_STACK_CHUNK_SIZE (16*1024)
66 struct _ts {
67 /* See Python/ceval.c for comments explaining most fields */
68
69 PyThreadState *prev;
70 PyThreadState *next;
71 PyInterpreterState *interp;
72
73 /* The global instrumentation version in high bits, plus flags indicating
74 when to break out of the interpreter loop in lower bits. See details in
75 pycore_ceval.h. */
76 uintptr_t eval_breaker;
77
78 struct {
79 /* Has been initialized to a safe state.
80
81 In order to be effective, this must be set to 0 during or right
82 after allocation. */
83 unsigned int initialized:1;
84
85 /* Has been bound to an OS thread. */
86 unsigned int bound:1;
87 /* Has been unbound from its OS thread. */
88 unsigned int unbound:1;
89 /* Has been bound aa current for the GILState API. */
90 unsigned int bound_gilstate:1;
91 /* Currently in use (maybe holds the GIL). */
92 unsigned int active:1;
93
94 /* various stages of finalization */
95 unsigned int finalizing:1;
96 unsigned int cleared:1;
97 unsigned int finalized:1;
98
99 /* padding to align to 4 bytes */
100 unsigned int :24;
101 } _status;
102 #ifdef Py_BUILD_CORE
103 # define _PyThreadState_WHENCE_NOTSET -1
104 # define _PyThreadState_WHENCE_UNKNOWN 0
105 # define _PyThreadState_WHENCE_INIT 1
106 # define _PyThreadState_WHENCE_FINI 2
107 # define _PyThreadState_WHENCE_THREADING 3
108 # define _PyThreadState_WHENCE_GILSTATE 4
109 # define _PyThreadState_WHENCE_EXEC 5
110 #endif
111
112 /* Currently holds the GIL. Must be its own field to avoid data races */
113 int holds_gil;
114
115 int _whence;
116
117 /* Thread state (_Py_THREAD_ATTACHED, _Py_THREAD_DETACHED, _Py_THREAD_SUSPENDED).
118 See Include/internal/pycore_pystate.h for more details. */
119 int state;
120
121 int py_recursion_remaining;
122 int py_recursion_limit;
123 int recursion_headroom; /* Allow 50 more calls to handle any errors. */
124
125 /* 'tracing' keeps track of the execution depth when tracing/profiling.
126 This is to prevent the actual trace/profile code from being recorded in
127 the trace/profile. */
128 int tracing;
129 int what_event; /* The event currently being monitored, if any. */
130
131 /* Pointer to currently executing frame. */
132 struct _PyInterpreterFrame *current_frame;
133
134 Py_tracefunc c_profilefunc;
135 Py_tracefunc c_tracefunc;
136 PyObject *c_profileobj;
137 PyObject *c_traceobj;
138
139 /* The exception currently being raised */
140 PyObject *current_exception;
141
142 /* Pointer to the top of the exception stack for the exceptions
143 * we may be currently handling. (See _PyErr_StackItem above.)
144 * This is never NULL. */
145 _PyErr_StackItem *exc_info;
146
147 PyObject *dict; /* Stores per-thread state */
148
149 int gilstate_counter;
150
151 PyObject *async_exc; /* Asynchronous exception to raise */
152 unsigned long thread_id; /* Thread id where this tstate was created */
153
154 /* Native thread id where this tstate was created. This will be 0 except on
155 * those platforms that have the notion of native thread id, for which the
156 * macro PY_HAVE_THREAD_NATIVE_ID is then defined.
157 */
158 unsigned long native_thread_id;
159
160 PyObject *delete_later;
161
162 /* Tagged pointer to top-most critical section, or zero if there is no
163 * active critical section. Critical sections are only used in
164 * `--disable-gil` builds (i.e., when Py_GIL_DISABLED is defined to 1). In the
165 * default build, this field is always zero.
166 */
167 uintptr_t critical_section;
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 _PyStackChunk *datastack_chunk;
181 PyObject **datastack_top;
182 PyObject **datastack_limit;
183 /* XXX signal handlers should also be here */
184
185 /* The following fields are here to avoid allocation during init.
186 The data is exposed through PyThreadState pointer fields.
187 These fields should not be accessed directly outside of init.
188 This is indicated by an underscore prefix on the field names.
189
190 All other PyInterpreterState pointer fields are populated when
191 needed and default to NULL.
192 */
193 // Note some fields do not have a leading underscore for backward
194 // compatibility. See https://bugs.python.org/issue45953#msg412046.
195
196 /* The thread's exception stack entry. (Always the last entry.) */
197 _PyErr_StackItem exc_state;
198
199 PyObject *current_executor;
200
201 uint64_t dict_global_version;
202
203 /* Used to store/retrieve `threading.local` keys/values for this thread */
204 PyObject *threading_local_key;
205
206 /* Used by `threading.local`s to be remove keys/values for dying threads.
207 The PyThreadObject must hold the only reference to this value.
208 */
209 PyObject *threading_local_sentinel;
210 _PyRemoteDebuggerSupport remote_debugger_support;
211
212 _PyStackChunk *datastack_cached_chunk;
213 };
214
215 /* other API */
216
217 /* Similar to PyThreadState_Get(), but don't issue a fatal error
218 * if it is NULL. */
219 PyAPI_FUNC(PyThreadState *) PyThreadState_GetUnchecked(void);
220
221 // Deprecated alias kept for backward compatibility
222 Py_DEPRECATED(3.14) static inline PyThreadState*
223 _PyThreadState_UncheckedGet(void)
224 {
225 return PyThreadState_GetUnchecked();
226 }
227
228 // Disable tracing and profiling.
229 PyAPI_FUNC(void) PyThreadState_EnterTracing(PyThreadState *tstate);
230
231 // Reset tracing and profiling: enable them if a trace function or a profile
232 // function is set, otherwise disable them.
233 PyAPI_FUNC(void) PyThreadState_LeaveTracing(PyThreadState *tstate);
234
235 /* PyGILState */
236
237 /* Helper/diagnostic function - return 1 if the current thread
238 currently holds the GIL, 0 otherwise.
239
240 The function returns 1 if _PyGILState_check_enabled is non-zero. */
241 PyAPI_FUNC(int) PyGILState_Check(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 // Set the stack protection start address and stack protection size
249 // of a Python thread state
250 PyAPI_FUNC(int) PyUnstable_ThreadState_SetStackProtection(
251 PyThreadState *tstate,
252 void *stack_start_addr, // Stack start address
253 size_t stack_size); // Stack size (in bytes)
254
255 // Reset the stack protection start address and stack protection size
256 // of a Python thread state
257 PyAPI_FUNC(void) PyUnstable_ThreadState_ResetStackProtection(
258 PyThreadState *tstate);
259
260 /* Routines for advanced debuggers, requested by David Beazley.
261 Don't use unless you know what you are doing! */
262 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void);
263 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
264 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
265 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
266 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
267 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
268
269 /* Frame evaluation API */
270
271 typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
272
273 PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
274 PyInterpreterState *interp);
275 PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
276 PyInterpreterState *interp,
277 _PyFrameEvalFunction eval_frame);