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_freelist.h" // _PyFreeListState
12 #include "pycore_runtime.h" // _PyRuntime
13 #include "pycore_tstate.h" // _PyThreadStateImpl
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 // State transition diagram:
33 //
34 // (bound thread) (stop-the-world thread)
35 // [attached] <-> [detached] <-> [suspended]
36 // | ^
37 // +---------------------------->---------------------------+
38 // (bound thread)
39 //
40 // The (bound thread) and (stop-the-world thread) labels indicate which thread
41 // is allowed to perform the transition.
42 #define _Py_THREAD_DETACHED 0
43 #define _Py_THREAD_ATTACHED 1
44 #define _Py_THREAD_SUSPENDED 2
45
46
47 /* Check if the current thread is the main thread.
48 Use _Py_IsMainInterpreter() to check if it's the main interpreter. */
49 static inline int
_Py_IsMainThread(void)50 _Py_IsMainThread(void)
51 {
52 unsigned long thread = PyThread_get_thread_ident();
53 return (thread == _PyRuntime.main_thread);
54 }
55
56
57 static inline PyInterpreterState *
_PyInterpreterState_Main(void)58 _PyInterpreterState_Main(void)
59 {
60 return _PyRuntime.interpreters.main;
61 }
62
63 static inline int
_Py_IsMainInterpreter(PyInterpreterState * interp)64 _Py_IsMainInterpreter(PyInterpreterState *interp)
65 {
66 return (interp == _PyInterpreterState_Main());
67 }
68
69 static inline int
_Py_IsMainInterpreterFinalizing(PyInterpreterState * interp)70 _Py_IsMainInterpreterFinalizing(PyInterpreterState *interp)
71 {
72 /* bpo-39877: Access _PyRuntime directly rather than using
73 tstate->interp->runtime to support calls from Python daemon threads.
74 After Py_Finalize() has been called, tstate can be a dangling pointer:
75 point to PyThreadState freed memory. */
76 return (_PyRuntimeState_GetFinalizing(&_PyRuntime) != NULL &&
77 interp == &_PyRuntime._main_interpreter);
78 }
79
80 // Export for _interpreters module.
81 PyAPI_FUNC(PyObject *) _PyInterpreterState_GetIDObject(PyInterpreterState *);
82
83 // Export for _interpreters module.
84 PyAPI_FUNC(int) _PyInterpreterState_SetRunningMain(PyInterpreterState *);
85 PyAPI_FUNC(void) _PyInterpreterState_SetNotRunningMain(PyInterpreterState *);
86 PyAPI_FUNC(int) _PyInterpreterState_IsRunningMain(PyInterpreterState *);
87 PyAPI_FUNC(int) _PyInterpreterState_FailIfRunningMain(PyInterpreterState *);
88
89 extern int _PyThreadState_IsRunningMain(PyThreadState *);
90 extern void _PyInterpreterState_ReinitRunningMain(PyThreadState *);
91
92
93 static inline const PyConfig *
_Py_GetMainConfig(void)94 _Py_GetMainConfig(void)
95 {
96 PyInterpreterState *interp = _PyInterpreterState_Main();
97 if (interp == NULL) {
98 return NULL;
99 }
100 return _PyInterpreterState_GetConfig(interp);
101 }
102
103
104 /* Only handle signals on the main thread of the main interpreter. */
105 static inline int
_Py_ThreadCanHandleSignals(PyInterpreterState * interp)106 _Py_ThreadCanHandleSignals(PyInterpreterState *interp)
107 {
108 return (_Py_IsMainThread() && _Py_IsMainInterpreter(interp));
109 }
110
111
112 /* Variable and static inline functions for in-line access to current thread
113 and interpreter state */
114
115 #if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE)
116 extern _Py_thread_local PyThreadState *_Py_tss_tstate;
117 #endif
118
119 #ifndef NDEBUG
120 extern int _PyThreadState_CheckConsistency(PyThreadState *tstate);
121 #endif
122
123 int _PyThreadState_MustExit(PyThreadState *tstate);
124
125 // Export for most shared extensions, used via _PyThreadState_GET() static
126 // inline function.
127 PyAPI_FUNC(PyThreadState *) _PyThreadState_GetCurrent(void);
128
129 /* Get the current Python thread state.
130
131 This function is unsafe: it does not check for error and it can return NULL.
132
133 The caller must hold the GIL.
134
135 See also PyThreadState_Get() and PyThreadState_GetUnchecked(). */
136 static inline PyThreadState*
_PyThreadState_GET(void)137 _PyThreadState_GET(void)
138 {
139 #if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE)
140 return _Py_tss_tstate;
141 #else
142 return _PyThreadState_GetCurrent();
143 #endif
144 }
145
146 // Attaches the current thread to the interpreter.
147 //
148 // This may block while acquiring the GIL (if the GIL is enabled) or while
149 // waiting for a stop-the-world pause (if the GIL is disabled).
150 //
151 // High-level code should generally call PyEval_RestoreThread() instead, which
152 // calls this function.
153 extern void _PyThreadState_Attach(PyThreadState *tstate);
154
155 // Detaches the current thread from the interpreter.
156 //
157 // High-level code should generally call PyEval_SaveThread() instead, which
158 // calls this function.
159 extern void _PyThreadState_Detach(PyThreadState *tstate);
160
161 // Detaches the current thread to the "suspended" state if a stop-the-world
162 // pause is in progress.
163 //
164 // If there is no stop-the-world pause in progress, then the thread switches
165 // to the "detached" state.
166 extern void _PyThreadState_Suspend(PyThreadState *tstate);
167
168 // Perform a stop-the-world pause for all threads in the all interpreters.
169 //
170 // Threads in the "attached" state are paused and transitioned to the "GC"
171 // state. Threads in the "detached" state switch to the "GC" state, preventing
172 // them from reattaching until the stop-the-world pause is complete.
173 //
174 // NOTE: This is a no-op outside of Py_GIL_DISABLED builds.
175 extern void _PyEval_StopTheWorldAll(_PyRuntimeState *runtime);
176 extern void _PyEval_StartTheWorldAll(_PyRuntimeState *runtime);
177
178 // Perform a stop-the-world pause for threads in the specified interpreter.
179 //
180 // NOTE: This is a no-op outside of Py_GIL_DISABLED builds.
181 extern void _PyEval_StopTheWorld(PyInterpreterState *interp);
182 extern void _PyEval_StartTheWorld(PyInterpreterState *interp);
183
184
185 static inline void
_Py_EnsureFuncTstateNotNULL(const char * func,PyThreadState * tstate)186 _Py_EnsureFuncTstateNotNULL(const char *func, PyThreadState *tstate)
187 {
188 if (tstate == NULL) {
189 _Py_FatalErrorFunc(func,
190 "the function must be called with the GIL held, "
191 "after Python initialization and before Python finalization, "
192 "but the GIL is released (the current Python thread state is NULL)");
193 }
194 }
195
196 // Call Py_FatalError() if tstate is NULL
197 #define _Py_EnsureTstateNotNULL(tstate) \
198 _Py_EnsureFuncTstateNotNULL(__func__, (tstate))
199
200
201 /* Get the current interpreter state.
202
203 The function is unsafe: it does not check for error and it can return NULL.
204
205 The caller must hold the GIL.
206
207 See also PyInterpreterState_Get()
208 and _PyGILState_GetInterpreterStateUnsafe(). */
_PyInterpreterState_GET(void)209 static inline PyInterpreterState* _PyInterpreterState_GET(void) {
210 PyThreadState *tstate = _PyThreadState_GET();
211 #ifdef Py_DEBUG
212 _Py_EnsureTstateNotNULL(tstate);
213 #endif
214 return tstate->interp;
215 }
216
217
218 // PyThreadState functions
219
220 // Export for _testinternalcapi
221 PyAPI_FUNC(PyThreadState *) _PyThreadState_New(
222 PyInterpreterState *interp,
223 int whence);
224 extern void _PyThreadState_Bind(PyThreadState *tstate);
225 PyAPI_FUNC(PyThreadState *) _PyThreadState_NewBound(
226 PyInterpreterState *interp,
227 int whence);
228 extern PyThreadState * _PyThreadState_RemoveExcept(PyThreadState *tstate);
229 extern void _PyThreadState_DeleteList(PyThreadState *list);
230 extern void _PyThreadState_ClearMimallocHeaps(PyThreadState *tstate);
231
232 // Export for '_testinternalcapi' shared extension
233 PyAPI_FUNC(PyObject*) _PyThreadState_GetDict(PyThreadState *tstate);
234
235 /* The implementation of sys._current_exceptions() Returns a dict mapping
236 thread id to that thread's current exception.
237 */
238 extern PyObject* _PyThread_CurrentExceptions(void);
239
240
241 /* Other */
242
243 extern PyThreadState * _PyThreadState_Swap(
244 _PyRuntimeState *runtime,
245 PyThreadState *newts);
246
247 extern PyStatus _PyInterpreterState_Enable(_PyRuntimeState *runtime);
248
249 #ifdef HAVE_FORK
250 extern PyStatus _PyInterpreterState_DeleteExceptMain(_PyRuntimeState *runtime);
251 extern void _PySignal_AfterFork(void);
252 #endif
253
254 // Export for the stable ABI
255 PyAPI_FUNC(int) _PyState_AddModule(
256 PyThreadState *tstate,
257 PyObject* module,
258 PyModuleDef* def);
259
260
261 extern int _PyOS_InterruptOccurred(PyThreadState *tstate);
262
263 #define HEAD_LOCK(runtime) \
264 PyMutex_LockFlags(&(runtime)->interpreters.mutex, _Py_LOCK_DONT_DETACH)
265 #define HEAD_UNLOCK(runtime) \
266 PyMutex_Unlock(&(runtime)->interpreters.mutex)
267
268 // Get the configuration of the current interpreter.
269 // The caller must hold the GIL.
270 // Export for test_peg_generator.
271 PyAPI_FUNC(const PyConfig*) _Py_GetConfig(void);
272
273 // Get the single PyInterpreterState used by this process' GILState
274 // implementation.
275 //
276 // This function doesn't check for error. Return NULL before _PyGILState_Init()
277 // is called and after _PyGILState_Fini() is called.
278 //
279 // See also PyInterpreterState_Get() and _PyInterpreterState_GET().
280 extern PyInterpreterState* _PyGILState_GetInterpreterStateUnsafe(void);
281
_Py_object_freelists_GET(void)282 static inline struct _Py_object_freelists* _Py_object_freelists_GET(void)
283 {
284 PyThreadState *tstate = _PyThreadState_GET();
285 #ifdef Py_DEBUG
286 _Py_EnsureTstateNotNULL(tstate);
287 #endif
288
289 #ifdef Py_GIL_DISABLED
290 return &((_PyThreadStateImpl*)tstate)->freelists;
291 #else
292 return &tstate->interp->object_state.freelists;
293 #endif
294 }
295
296 #ifdef __cplusplus
297 }
298 #endif
299 #endif /* !Py_INTERNAL_PYSTATE_H */
300