Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.14/internal/pycore_pystate.h
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 */
