Debian Codegraph @

Include/internal/pycore_pystate.h

raw
1 #ifndef Py_INTERNAL_PYSTATE_H
2 #define Py_INTERNAL_PYSTATE_H
3 #ifdef __cplusplus
4 extern "C" {
5 #endif
6
7 #ifndef Py_BUILD_CORE
8 # error "this header requires Py_BUILD_CORE define"
9 #endif
10
11 #include "pycore_pythonrun.h" // _PyOS_STACK_MARGIN_SHIFT
12 #include "pycore_typedefs.h" // _PyRuntimeState
13 #include "pycore_tstate.h"
14
15
16 // Values for PyThreadState.state. A thread must be in the "attached" state
17 // before calling most Python APIs. If the GIL is enabled, then "attached"
18 // implies that the thread holds the GIL and "detached" implies that the
19 // thread does not hold the GIL (or is in the process of releasing it). In
20 // `--disable-gil` builds, multiple threads may be "attached" to the same
21 // interpreter at the same time. Only the "bound" thread may perform the
22 // transitions between "attached" and "detached" on its own PyThreadState.
23 //
24 // The "suspended" state is used to implement stop-the-world pauses, such as
25 // for cyclic garbage collection. It is only used in `--disable-gil` builds.
26 // The "suspended" state is similar to the "detached" state in that in both
27 // states the thread is not allowed to call most Python APIs. However, unlike
28 // the "detached" state, a thread may not transition itself out from the
29 // "suspended" state. Only the thread performing a stop-the-world pause may
30 // transition a thread from the "suspended" state back to the "detached" state.
31 //
32 // The "shutting down" state is used when the interpreter is being finalized.
33 // Threads in this state can't do anything other than block the OS thread.
34 // (See _PyThreadState_HangThread).
35 //
36 // State transition diagram:
37 //
38 // (bound thread) (stop-the-world thread)
39 // [attached] <-> [detached] <-> [suspended]
40 // | ^
41 // +---------------------------->---------------------------+
42 // (bound thread)
43 //
44 // The (bound thread) and (stop-the-world thread) labels indicate which thread
45 // is allowed to perform the transition.
46 #define _Py_THREAD_DETACHED 0
47 #define _Py_THREAD_ATTACHED 1
48 #define _Py_THREAD_SUSPENDED 2
49 #define _Py_THREAD_SHUTTING_DOWN 3
50
51
52 /* Check if the current thread is the main thread.
53 Use _Py_IsMainInterpreter() to check if it's the main interpreter. */
54 extern int _Py_IsMainThread(void);
55
56 // Export for '_testinternalcapi' shared extension
57 PyAPI_FUNC(PyInterpreterState*) _PyInterpreterState_Main(void);
58
59 static inline int
60 _Py_IsMainInterpreter(PyInterpreterState *interp)
61 {
62 return (interp == _PyInterpreterState_Main());
63 }
64
65 extern int _Py_IsMainInterpreterFinalizing(PyInterpreterState *interp);
66
67 // Export for _interpreters module.
68 PyAPI_FUNC(PyObject *) _PyInterpreterState_GetIDObject(PyInterpreterState *);
69
70 // Export for _interpreters module.
71 PyAPI_FUNC(int) _PyInterpreterState_SetRunningMain(PyInterpreterState *);
72 PyAPI_FUNC(void) _PyInterpreterState_SetNotRunningMain(PyInterpreterState *);
73 PyAPI_FUNC(int) _PyInterpreterState_IsRunningMain(PyInterpreterState *);
74 PyAPI_FUNC(void) _PyErr_SetInterpreterAlreadyRunning(void);
75
76 extern int _PyThreadState_IsRunningMain(PyThreadState *);
77 extern void _PyInterpreterState_ReinitRunningMain(PyThreadState *);
78 extern const PyConfig* _Py_GetMainConfig(void);
79
80
81 /* Only handle signals on the main thread of the main interpreter. */
82 static inline int
83 _Py_ThreadCanHandleSignals(PyInterpreterState *interp)
84 {
85 return (_Py_IsMainThread() && _Py_IsMainInterpreter(interp));
86 }
87
88
89 /* Variable and static inline functions for in-line access to current thread
90 and interpreter state */
91
92 #if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE)
93 extern _Py_thread_local PyThreadState *_Py_tss_tstate;
94 #endif
95
96 #ifndef NDEBUG
97 extern int _PyThreadState_CheckConsistency(PyThreadState *tstate);
98 #endif
99
100 extern int _PyThreadState_MustExit(PyThreadState *tstate);
101 extern void _PyThreadState_HangThread(PyThreadState *tstate);
102
103 // Export for most shared extensions, used via _PyThreadState_GET() static
104 // inline function.
105 PyAPI_FUNC(PyThreadState *) _PyThreadState_GetCurrent(void);
106
107 /* Get the current Python thread state.
108
109 This function is unsafe: it does not check for error and it can return NULL.
110
111 The caller must hold the GIL.
112
113 See also PyThreadState_Get() and PyThreadState_GetUnchecked(). */
114 static inline PyThreadState*
115 _PyThreadState_GET(void)
116 {
117 #if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE)
118 return _Py_tss_tstate;
119 #else
120 return _PyThreadState_GetCurrent();
121 #endif
122 }
123
124 static inline int
125 _PyThreadState_IsAttached(PyThreadState *tstate)
126 {
127 return (_Py_atomic_load_int_relaxed(&tstate->state) == _Py_THREAD_ATTACHED);
128 }
129
130 // Attaches the current thread to the interpreter.
131 //
132 // This may block while acquiring the GIL (if the GIL is enabled) or while
133 // waiting for a stop-the-world pause (if the GIL is disabled).
134 //
135 // High-level code should generally call PyEval_RestoreThread() instead, which
136 // calls this function.
137 extern void _PyThreadState_Attach(PyThreadState *tstate);
138
139 // Detaches the current thread from the interpreter.
140 //
141 // High-level code should generally call PyEval_SaveThread() instead, which
142 // calls this function.
143 extern void _PyThreadState_Detach(PyThreadState *tstate);
144
145 // Detaches the current thread to the "suspended" state if a stop-the-world
146 // pause is in progress.
147 //
148 // If there is no stop-the-world pause in progress, then the thread switches
149 // to the "detached" state.
150 extern void _PyThreadState_Suspend(PyThreadState *tstate);
151
152 // Mark the thread state as "shutting down". This is used during interpreter
153 // and runtime finalization. The thread may no longer attach to the
154 // interpreter and will instead block via _PyThreadState_HangThread().
155 extern void _PyThreadState_SetShuttingDown(PyThreadState *tstate);
156
157 // Perform a stop-the-world pause for all threads in the all interpreters.
158 //
159 // Threads in the "attached" state are paused and transitioned to the "GC"
160 // state. Threads in the "detached" state switch to the "GC" state, preventing
161 // them from reattaching until the stop-the-world pause is complete.
162 //
163 // NOTE: This is a no-op outside of Py_GIL_DISABLED builds.
164 extern void _PyEval_StopTheWorldAll(_PyRuntimeState *runtime);
165 extern void _PyEval_StartTheWorldAll(_PyRuntimeState *runtime);
166
167 // Perform a stop-the-world pause for threads in the specified interpreter.
168 //
169 // NOTE: This is a no-op outside of Py_GIL_DISABLED builds.
170 extern PyAPI_FUNC(void) _PyEval_StopTheWorld(PyInterpreterState *interp);
171 extern PyAPI_FUNC(void) _PyEval_StartTheWorld(PyInterpreterState *interp);
172
173
174 static inline void
175 _Py_EnsureFuncTstateNotNULL(const char *func, PyThreadState *tstate)
176 {
177 if (tstate == NULL) {
178 #ifndef Py_GIL_DISABLED
179 _Py_FatalErrorFunc(func,
180 "the function must be called with the GIL held, "
181 "after Python initialization and before Python finalization, "
182 "but the GIL is released (the current Python thread state is NULL)");
183 #else
184 _Py_FatalErrorFunc(func,
185 "the function must be called with an active thread state, "
186 "after Python initialization and before Python finalization, "
187 "but it was called without an active thread state. "
188 "Are you trying to call the C API inside of a Py_BEGIN_ALLOW_THREADS block?");
189 #endif
190 }
191 }
192
193 // Call Py_FatalError() if tstate is NULL
194 #define _Py_EnsureTstateNotNULL(tstate) \
195 _Py_EnsureFuncTstateNotNULL(__func__, (tstate))
196
197
198 /* Get the current interpreter state.
199
200 The function is unsafe: it does not check for error and it can return NULL.
201
202 The caller must hold the GIL.
203
204 See also PyInterpreterState_Get()
205 and _PyGILState_GetInterpreterStateUnsafe(). */
206 static inline PyInterpreterState* _PyInterpreterState_GET(void) {
207 PyThreadState *tstate = _PyThreadState_GET();
208 #ifdef Py_DEBUG
209 _Py_EnsureTstateNotNULL(tstate);
210 #endif
211 return tstate->interp;
212 }
213
214
215 // PyThreadState functions
216
217 // Export for _testinternalcapi
218 PyAPI_FUNC(PyThreadState *) _PyThreadState_New(
219 PyInterpreterState *interp,
220 int whence);
221 extern void _PyThreadState_Bind(PyThreadState *tstate);
222 PyAPI_FUNC(PyThreadState *) _PyThreadState_NewBound(
223 PyInterpreterState *interp,
224 int whence);
225 extern PyThreadState * _PyThreadState_RemoveExcept(PyThreadState *tstate);
226 extern void _PyThreadState_DeleteList(PyThreadState *list, int is_after_fork);
227 extern void _PyThreadState_ClearMimallocHeaps(PyThreadState *tstate);
228
229 // Export for '_testinternalcapi' shared extension
230 PyAPI_FUNC(PyObject*) _PyThreadState_GetDict(PyThreadState *tstate);
231
232 /* The implementation of sys._current_exceptions() Returns a dict mapping
233 thread id to that thread's current exception.
234 */
235 extern PyObject* _PyThread_CurrentExceptions(void);
236
237
238 /* Other */
239
240 extern PyThreadState * _PyThreadState_Swap(
241 _PyRuntimeState *runtime,
242 PyThreadState *newts);
243
244 extern PyStatus _PyInterpreterState_Enable(_PyRuntimeState *runtime);
245
246 #ifdef HAVE_FORK
247 extern PyStatus _PyInterpreterState_DeleteExceptMain(_PyRuntimeState *runtime);
248 extern void _PySignal_AfterFork(void);
249 #endif
250
251 // Export for the stable ABI
252 PyAPI_FUNC(int) _PyState_AddModule(
253 PyThreadState *tstate,
254 PyObject* module,
255 PyModuleDef* def);
256
257
258 extern int _PyOS_InterruptOccurred(PyThreadState *tstate);
259
260 #define HEAD_LOCK(runtime) \
261 PyMutex_LockFlags(&(runtime)->interpreters.mutex, _Py_LOCK_DONT_DETACH)
262 #define HEAD_UNLOCK(runtime) \
263 PyMutex_Unlock(&(runtime)->interpreters.mutex)
264
265 #define _Py_FOR_EACH_TSTATE_UNLOCKED(interp, t) \
266 for (PyThreadState *t = interp->threads.head; t; t = t->next)
267 #define _Py_FOR_EACH_TSTATE_BEGIN(interp, t) \
268 HEAD_LOCK(interp->runtime); \
269 _Py_FOR_EACH_TSTATE_UNLOCKED(interp, t)
270 #define _Py_FOR_EACH_TSTATE_END(interp) \
271 HEAD_UNLOCK(interp->runtime)
272
273
274 // Get the configuration of the current interpreter.
275 // The caller must hold the GIL.
276 // Export for test_peg_generator.
277 PyAPI_FUNC(const PyConfig*) _Py_GetConfig(void);
278
279 // Get the single PyInterpreterState used by this process' GILState
280 // implementation.
281 //
282 // This function doesn't check for error. Return NULL before _PyGILState_Init()
283 // is called and after _PyGILState_Fini() is called.
284 //
285 // See also PyInterpreterState_Get() and _PyInterpreterState_GET().
286 extern PyInterpreterState* _PyGILState_GetInterpreterStateUnsafe(void);
287
288 extern PyObject * _Py_GetMainModule(PyThreadState *);
289 extern int _Py_CheckMainModule(PyObject *module);
290
291 #ifndef NDEBUG
292 /* Modern equivalent of assert(PyGILState_Check()) */
293 static inline void
294 _Py_AssertHoldsTstateFunc(const char *func)
295 {
296 PyThreadState *tstate = _PyThreadState_GET();
297 _Py_EnsureFuncTstateNotNULL(func, tstate);
298 }
299 #define _Py_AssertHoldsTstate() _Py_AssertHoldsTstateFunc(__func__)
300 #else
301 #define _Py_AssertHoldsTstate()
302 #endif
303
304 #if !_Py__has_builtin(__builtin_frame_address) && !defined(__GNUC__) && !defined(_MSC_VER)
305 static uintptr_t return_pointer_as_int(char* p) {
306 return (uintptr_t)p;
307 }
308 #endif
309
310 static inline uintptr_t
311 _Py_get_machine_stack_pointer(void) {
312 #if _Py__has_builtin(__builtin_frame_address) || defined(__GNUC__)
313 return (uintptr_t)__builtin_frame_address(0);
314 #elif defined(_MSC_VER)
315 return (uintptr_t)_AddressOfReturnAddress();
316 #else
317 char here;
318 /* Avoid compiler warning about returning stack address */
319 return return_pointer_as_int(&here);
320 #endif
321 }
322
323 static inline intptr_t
324 _Py_RecursionLimit_GetMargin(PyThreadState *tstate)
325 {
326 _PyThreadStateImpl *_tstate = (_PyThreadStateImpl *)tstate;
327 assert(_tstate->c_stack_hard_limit != 0);
328 intptr_t here_addr = _Py_get_machine_stack_pointer();
329 #if _Py_STACK_GROWS_DOWN
330 return Py_ARITHMETIC_RIGHT_SHIFT(intptr_t, here_addr - (intptr_t)_tstate->c_stack_soft_limit, _PyOS_STACK_MARGIN_SHIFT);
331 #else
332 return Py_ARITHMETIC_RIGHT_SHIFT(intptr_t, (intptr_t)_tstate->c_stack_soft_limit - here_addr, _PyOS_STACK_MARGIN_SHIFT);
333 #endif
334 }
335
336 #ifdef __cplusplus
337 }
338 #endif
339 #endif /* !Py_INTERNAL_PYSTATE_H */