python3.13/internal/pycore_pystate.h

0001 #ifndef Py_INTERNAL_PYSTATE_H
0002 #define Py_INTERNAL_PYSTATE_H
0003 #ifdef __cplusplus
0004 extern "C" {
0005 #endif
0006
0007 #ifndef Py_BUILD_CORE
0008 #  error "this header requires Py_BUILD_CORE define"
0009 #endif
0010
0011 #include "pycore_freelist.h"      // _PyFreeListState
0012 #include "pycore_runtime.h"       // _PyRuntime
0013 #include "pycore_tstate.h"        // _PyThreadStateImpl
0014
0015
0016 // Values for PyThreadState.state. A thread must be in the "attached" state
0017 // before calling most Python APIs. If the GIL is enabled, then "attached"
0018 // implies that the thread holds the GIL and "detached" implies that the
0019 // thread does not hold the GIL (or is in the process of releasing it). In
0020 // `--disable-gil` builds, multiple threads may be "attached" to the same
0021 // interpreter at the same time. Only the "bound" thread may perform the
0022 // transitions between "attached" and "detached" on its own PyThreadState.
0023 //
0024 // The "suspended" state is used to implement stop-the-world pauses, such as
0025 // for cyclic garbage collection. It is only used in `--disable-gil` builds.
0026 // The "suspended" state is similar to the "detached" state in that in both
0027 // states the thread is not allowed to call most Python APIs. However, unlike
0028 // the "detached" state, a thread may not transition itself out from the
0029 // "suspended" state. Only the thread performing a stop-the-world pause may
0030 // transition a thread from the "suspended" state back to the "detached" state.
0031 //
0032 // State transition diagram:
0033 //
0034 //            (bound thread)        (stop-the-world thread)
0035 // [attached]       <->       [detached]       <->       [suspended]
0036 //   |                                                        ^
0037 //   +---------------------------->---------------------------+
0038 //                          (bound thread)
0039 //
0040 // The (bound thread) and (stop-the-world thread) labels indicate which thread
0041 // is allowed to perform the transition.
0042 #define _Py_THREAD_DETACHED     0
0043 #define _Py_THREAD_ATTACHED     1
0044 #define _Py_THREAD_SUSPENDED    2
0045
0046
0047 /* Check if the current thread is the main thread.
0048    Use _Py_IsMainInterpreter() to check if it's the main interpreter. */
0049 static inline int
0050 _Py_IsMainThread(void)
0051 {
0052     unsigned long thread = PyThread_get_thread_ident();
0053     return (thread == _PyRuntime.main_thread);
0054 }
0055
0056
0057 static inline PyInterpreterState *
0058 _PyInterpreterState_Main(void)
0059 {
0060     return _PyRuntime.interpreters.main;
0061 }
0062
0063 static inline int
0064 _Py_IsMainInterpreter(PyInterpreterState *interp)
0065 {
0066     return (interp == _PyInterpreterState_Main());
0067 }
0068
0069 static inline int
0070 _Py_IsMainInterpreterFinalizing(PyInterpreterState *interp)
0071 {
0072     /* bpo-39877: Access _PyRuntime directly rather than using
0073        tstate->interp->runtime to support calls from Python daemon threads.
0074        After Py_Finalize() has been called, tstate can be a dangling pointer:
0075        point to PyThreadState freed memory. */
0076     return (_PyRuntimeState_GetFinalizing(&_PyRuntime) != NULL &&
0077             interp == &_PyRuntime._main_interpreter);
0078 }
0079
0080 // Export for _interpreters module.
0081 PyAPI_FUNC(PyObject *) _PyInterpreterState_GetIDObject(PyInterpreterState *);
0082
0083 // Export for _interpreters module.
0084 PyAPI_FUNC(int) _PyInterpreterState_SetRunningMain(PyInterpreterState *);
0085 PyAPI_FUNC(void) _PyInterpreterState_SetNotRunningMain(PyInterpreterState *);
0086 PyAPI_FUNC(int) _PyInterpreterState_IsRunningMain(PyInterpreterState *);
0087 PyAPI_FUNC(int) _PyInterpreterState_FailIfRunningMain(PyInterpreterState *);
0088
0089 extern int _PyThreadState_IsRunningMain(PyThreadState *);
0090 extern void _PyInterpreterState_ReinitRunningMain(PyThreadState *);
0091
0092
0093 static inline const PyConfig *
0094 _Py_GetMainConfig(void)
0095 {
0096     PyInterpreterState *interp = _PyInterpreterState_Main();
0097     if (interp == NULL) {
0098         return NULL;
0099     }
0100     return _PyInterpreterState_GetConfig(interp);
0101 }
0102
0103
0104 /* Only handle signals on the main thread of the main interpreter. */
0105 static inline int
0106 _Py_ThreadCanHandleSignals(PyInterpreterState *interp)
0107 {
0108     return (_Py_IsMainThread() && _Py_IsMainInterpreter(interp));
0109 }
0110
0111
0112 /* Variable and static inline functions for in-line access to current thread
0113    and interpreter state */
0114
0115 #if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE)
0116 extern _Py_thread_local PyThreadState *_Py_tss_tstate;
0117 #endif
0118
0119 #ifndef NDEBUG
0120 extern int _PyThreadState_CheckConsistency(PyThreadState *tstate);
0121 #endif
0122
0123 int _PyThreadState_MustExit(PyThreadState *tstate);
0124
0125 // Export for most shared extensions, used via _PyThreadState_GET() static
0126 // inline function.
0127 PyAPI_FUNC(PyThreadState *) _PyThreadState_GetCurrent(void);
0128
0129 /* Get the current Python thread state.
0130
0131    This function is unsafe: it does not check for error and it can return NULL.
0132
0133    The caller must hold the GIL.
0134
0135    See also PyThreadState_Get() and PyThreadState_GetUnchecked(). */
0136 static inline PyThreadState*
0137 _PyThreadState_GET(void)
0138 {
0139 #if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE)
0140     return _Py_tss_tstate;
0141 #else
0142     return _PyThreadState_GetCurrent();
0143 #endif
0144 }
0145
0146 // Attaches the current thread to the interpreter.
0147 //
0148 // This may block while acquiring the GIL (if the GIL is enabled) or while
0149 // waiting for a stop-the-world pause (if the GIL is disabled).
0150 //
0151 // High-level code should generally call PyEval_RestoreThread() instead, which
0152 // calls this function.
0153 extern void _PyThreadState_Attach(PyThreadState *tstate);
0154
0155 // Detaches the current thread from the interpreter.
0156 //
0157 // High-level code should generally call PyEval_SaveThread() instead, which
0158 // calls this function.
0159 extern void _PyThreadState_Detach(PyThreadState *tstate);
0160
0161 // Detaches the current thread to the "suspended" state if a stop-the-world
0162 // pause is in progress.
0163 //
0164 // If there is no stop-the-world pause in progress, then the thread switches
0165 // to the "detached" state.
0166 extern void _PyThreadState_Suspend(PyThreadState *tstate);
0167
0168 // Perform a stop-the-world pause for all threads in the all interpreters.
0169 //
0170 // Threads in the "attached" state are paused and transitioned to the "GC"
0171 // state. Threads in the "detached" state switch to the "GC" state, preventing
0172 // them from reattaching until the stop-the-world pause is complete.
0173 //
0174 // NOTE: This is a no-op outside of Py_GIL_DISABLED builds.
0175 extern void _PyEval_StopTheWorldAll(_PyRuntimeState *runtime);
0176 extern void _PyEval_StartTheWorldAll(_PyRuntimeState *runtime);
0177
0178 // Perform a stop-the-world pause for threads in the specified interpreter.
0179 //
0180 // NOTE: This is a no-op outside of Py_GIL_DISABLED builds.
0181 extern void _PyEval_StopTheWorld(PyInterpreterState *interp);
0182 extern void _PyEval_StartTheWorld(PyInterpreterState *interp);
0183
0184
0185 static inline void
0186 _Py_EnsureFuncTstateNotNULL(const char *func, PyThreadState *tstate)
0187 {
0188     if (tstate == NULL) {
0189         _Py_FatalErrorFunc(func,
0190             "the function must be called with the GIL held, "
0191             "after Python initialization and before Python finalization, "
0192             "but the GIL is released (the current Python thread state is NULL)");
0193     }
0194 }
0195
0196 // Call Py_FatalError() if tstate is NULL
0197 #define _Py_EnsureTstateNotNULL(tstate) \
0198     _Py_EnsureFuncTstateNotNULL(__func__, (tstate))
0199
0200
0201 /* Get the current interpreter state.
0202
0203    The function is unsafe: it does not check for error and it can return NULL.
0204
0205    The caller must hold the GIL.
0206
0207    See also PyInterpreterState_Get()
0208    and _PyGILState_GetInterpreterStateUnsafe(). */
0209 static inline PyInterpreterState* _PyInterpreterState_GET(void) {
0210     PyThreadState *tstate = _PyThreadState_GET();
0211 #ifdef Py_DEBUG
0212     _Py_EnsureTstateNotNULL(tstate);
0213 #endif
0214     return tstate->interp;
0215 }
0216
0217
0218 // PyThreadState functions
0219
0220 // Export for _testinternalcapi
0221 PyAPI_FUNC(PyThreadState *) _PyThreadState_New(
0222     PyInterpreterState *interp,
0223     int whence);
0224 extern void _PyThreadState_Bind(PyThreadState *tstate);
0225 PyAPI_FUNC(PyThreadState *) _PyThreadState_NewBound(
0226     PyInterpreterState *interp,
0227     int whence);
0228 extern PyThreadState * _PyThreadState_RemoveExcept(PyThreadState *tstate);
0229 extern void _PyThreadState_DeleteList(PyThreadState *list);
0230 extern void _PyThreadState_ClearMimallocHeaps(PyThreadState *tstate);
0231
0232 // Export for '_testinternalcapi' shared extension
0233 PyAPI_FUNC(PyObject*) _PyThreadState_GetDict(PyThreadState *tstate);
0234
0235 /* The implementation of sys._current_exceptions()  Returns a dict mapping
0236    thread id to that thread's current exception.
0237 */
0238 extern PyObject* _PyThread_CurrentExceptions(void);
0239
0240
0241 /* Other */
0242
0243 extern PyThreadState * _PyThreadState_Swap(
0244     _PyRuntimeState *runtime,
0245     PyThreadState *newts);
0246
0247 extern PyStatus _PyInterpreterState_Enable(_PyRuntimeState *runtime);
0248
0249 #ifdef HAVE_FORK
0250 extern PyStatus _PyInterpreterState_DeleteExceptMain(_PyRuntimeState *runtime);
0251 extern void _PySignal_AfterFork(void);
0252 #endif
0253
0254 // Export for the stable ABI
0255 PyAPI_FUNC(int) _PyState_AddModule(
0256     PyThreadState *tstate,
0257     PyObject* module,
0258     PyModuleDef* def);
0259
0260
0261 extern int _PyOS_InterruptOccurred(PyThreadState *tstate);
0262
0263 #define HEAD_LOCK(runtime) \
0264     PyMutex_LockFlags(&(runtime)->interpreters.mutex, _Py_LOCK_DONT_DETACH)
0265 #define HEAD_UNLOCK(runtime) \
0266     PyMutex_Unlock(&(runtime)->interpreters.mutex)
0267
0268 // Get the configuration of the current interpreter.
0269 // The caller must hold the GIL.
0270 // Export for test_peg_generator.
0271 PyAPI_FUNC(const PyConfig*) _Py_GetConfig(void);
0272
0273 // Get the single PyInterpreterState used by this process' GILState
0274 // implementation.
0275 //
0276 // This function doesn't check for error. Return NULL before _PyGILState_Init()
0277 // is called and after _PyGILState_Fini() is called.
0278 //
0279 // See also PyInterpreterState_Get() and _PyInterpreterState_GET().
0280 extern PyInterpreterState* _PyGILState_GetInterpreterStateUnsafe(void);
0281
0282 static inline struct _Py_object_freelists* _Py_object_freelists_GET(void)
0283 {
0284     PyThreadState *tstate = _PyThreadState_GET();
0285 #ifdef Py_DEBUG
0286     _Py_EnsureTstateNotNULL(tstate);
0287 #endif
0288
0289 #ifdef Py_GIL_DISABLED
0290     return &((_PyThreadStateImpl*)tstate)->freelists;
0291 #else
0292     return &tstate->interp->object_state.freelists;
0293 #endif
0294 }
0295
0296 #ifdef __cplusplus
0297 }
0298 #endif
0299 #endif /* !Py_INTERNAL_PYSTATE_H */