1 2 /* Thread and interpreter state structures and their interfaces */ 3 4 5 #ifndef Py_PYSTATE_H 6 #define Py_PYSTATE_H 7 #ifdef __cplusplus 8 extern "C" { 9 #endif 10 11 #include "pythread.h" 12 13 /* This limitation is for performance and simplicity. If needed it can be 14 removed (with effort). */ 15 #define MAX_CO_EXTRA_USERS 255 16 17 /* State shared between threads */ 18 19 struct _ts; /* Forward */ 20 struct _is; /* Forward */ 21 struct _frame; /* Forward declaration for PyFrameObject. */ 22 23 #ifdef Py_LIMITED_API 24 typedef struct _is PyInterpreterState; 25 #else 26 typedef PyObject* (*_PyFrameEvalFunction)(struct _frame *, int); 27 28 29 typedef struct { 30 int install_signal_handlers; /* Install signal handlers? -1 means unset */ 31 32 int ignore_environment; /* -E, Py_IgnoreEnvironmentFlag */ 33 int use_hash_seed; /* PYTHONHASHSEED=x */ 34 unsigned long hash_seed; 35 const char *allocator; /* Memory allocator: _PyMem_SetupAllocators() */ 36 int dev_mode; /* PYTHONDEVMODE, -X dev */ 37 int faulthandler; /* PYTHONFAULTHANDLER, -X faulthandler */ 38 int tracemalloc; /* PYTHONTRACEMALLOC, -X tracemalloc=N */ 39 int import_time; /* PYTHONPROFILEIMPORTTIME, -X importtime */ 40 int show_ref_count; /* -X showrefcount */ 41 int show_alloc_count; /* -X showalloccount */ 42 int dump_refs; /* PYTHONDUMPREFS */ 43 int malloc_stats; /* PYTHONMALLOCSTATS */ 44 int coerce_c_locale; /* PYTHONCOERCECLOCALE, -1 means unknown */ 45 int coerce_c_locale_warn; /* PYTHONCOERCECLOCALE=warn */ 46 int utf8_mode; /* PYTHONUTF8, -X utf8; -1 means unknown */ 47 48 wchar_t *program_name; /* Program name, see also Py_GetProgramName() */ 49 int argc; /* Number of command line arguments, 50 -1 means unset */ 51 wchar_t **argv; /* Command line arguments */ 52 wchar_t *program; /* argv[0] or "" */ 53 54 int nxoption; /* Number of -X options */ 55 wchar_t **xoptions; /* -X options */ 56 57 int nwarnoption; /* Number of warnings options */ 58 wchar_t **warnoptions; /* Warnings options */ 59 60 /* Path configuration inputs */ 61 wchar_t *module_search_path_env; /* PYTHONPATH environment variable */ 62 wchar_t *home; /* PYTHONHOME environment variable, 63 see also Py_SetPythonHome(). */ 64 65 /* Path configuration outputs */ 66 int nmodule_search_path; /* Number of sys.path paths, 67 -1 means unset */ 68 wchar_t **module_search_paths; /* sys.path paths */ 69 wchar_t *executable; /* sys.executable */ 70 wchar_t *prefix; /* sys.prefix */ 71 wchar_t *base_prefix; /* sys.base_prefix */ 72 wchar_t *exec_prefix; /* sys.exec_prefix */ 73 wchar_t *base_exec_prefix; /* sys.base_exec_prefix */ 74 75 /* Private fields */ 76 int _disable_importlib; /* Needed by freeze_importlib */ 77 } _PyCoreConfig; 78 79 #define _PyCoreConfig_INIT \ 80 (_PyCoreConfig){ \ 81 .install_signal_handlers = -1, \ 82 .ignore_environment = -1, \ 83 .use_hash_seed = -1, \ 84 .coerce_c_locale = -1, \ 85 .faulthandler = -1, \ 86 .tracemalloc = -1, \ 87 .utf8_mode = -1, \ 88 .argc = -1, \ 89 .nmodule_search_path = -1} 90 /* Note: _PyCoreConfig_INIT sets other fields to 0/NULL */ 91 92 /* Placeholders while working on the new configuration API 93 * 94 * See PEP 432 for final anticipated contents 95 */ 96 typedef struct { 97 int install_signal_handlers; /* Install signal handlers? -1 means unset */ 98 PyObject *argv; /* sys.argv list, can be NULL */ 99 PyObject *executable; /* sys.executable str */ 100 PyObject *prefix; /* sys.prefix str */ 101 PyObject *base_prefix; /* sys.base_prefix str, can be NULL */ 102 PyObject *exec_prefix; /* sys.exec_prefix str */ 103 PyObject *base_exec_prefix; /* sys.base_exec_prefix str, can be NULL */ 104 PyObject *warnoptions; /* sys.warnoptions list, can be NULL */ 105 PyObject *xoptions; /* sys._xoptions dict, can be NULL */ 106 PyObject *module_search_path; /* sys.path list */ 107 } _PyMainInterpreterConfig; 108 109 #define _PyMainInterpreterConfig_INIT \ 110 (_PyMainInterpreterConfig){.install_signal_handlers = -1} 111 /* Note: _PyMainInterpreterConfig_INIT sets other fields to 0/NULL */ 112 113 typedef struct _is { 114 115 struct _is *next; 116 struct _ts *tstate_head; 117 118 int64_t id; 119 int64_t id_refcount; 120 PyThread_type_lock id_mutex; 121 122 PyObject *modules; 123 PyObject *modules_by_index; 124 PyObject *sysdict; 125 PyObject *builtins; 126 PyObject *importlib; 127 128 /* Used in Python/sysmodule.c. */ 129 int check_interval; 130 131 /* Used in Modules/_threadmodule.c. */ 132 long num_threads; 133 /* Support for runtime thread stack size tuning. 134 A value of 0 means using the platform's default stack size 135 or the size specified by the THREAD_STACK_SIZE macro. */ 136 /* Used in Python/thread.c. */ 137 size_t pythread_stacksize; 138 139 PyObject *codec_search_path; 140 PyObject *codec_search_cache; 141 PyObject *codec_error_registry; 142 int codecs_initialized; 143 int fscodec_initialized; 144 145 _PyCoreConfig core_config; 146 _PyMainInterpreterConfig config; 147 #ifdef HAVE_DLOPEN 148 int dlopenflags; 149 #endif 150 151 PyObject *builtins_copy; 152 PyObject *import_func; 153 /* Initialized to PyEval_EvalFrameDefault(). */ 154 _PyFrameEvalFunction eval_frame; 155 156 Py_ssize_t co_extra_user_count; 157 freefunc co_extra_freefuncs[MAX_CO_EXTRA_USERS]; 158 159 #ifdef HAVE_FORK 160 PyObject *before_forkers; 161 PyObject *after_forkers_parent; 162 PyObject *after_forkers_child; 163 #endif 164 /* AtExit module */ 165 void (*pyexitfunc)(PyObject *); 166 PyObject *pyexitmodule; 167 168 uint64_t tstate_next_unique_id; 169 } PyInterpreterState; 170 #endif /* !Py_LIMITED_API */ 171 172 173 /* State unique per thread */ 174 175 #ifndef Py_LIMITED_API 176 /* Py_tracefunc return -1 when raising an exception, or 0 for success. */ 177 typedef int (*Py_tracefunc)(PyObject *, struct _frame *, int, PyObject *); 178 179 /* The following values are used for 'what' for tracefunc functions 180 * 181 * To add a new kind of trace event, also update "trace_init" in 182 * Python/sysmodule.c to define the Python level event name 183 */ 184 #define PyTrace_CALL 0 185 #define PyTrace_EXCEPTION 1 186 #define PyTrace_LINE 2 187 #define PyTrace_RETURN 3 188 #define PyTrace_C_CALL 4 189 #define PyTrace_C_EXCEPTION 5 190 #define PyTrace_C_RETURN 6 191 #define PyTrace_OPCODE 7 192 #endif /* Py_LIMITED_API */ 193 194 #ifdef Py_LIMITED_API 195 typedef struct _ts PyThreadState; 196 #else 197 198 typedef struct _err_stackitem { 199 /* This struct represents an entry on the exception stack, which is a 200 * per-coroutine state. (Coroutine in the computer science sense, 201 * including the thread and generators). 202 * This ensures that the exception state is not impacted by "yields" 203 * from an except handler. 204 */ 205 PyObject *exc_type, *exc_value, *exc_traceback; 206 207 struct _err_stackitem *previous_item; 208 209 } _PyErr_StackItem; 210 211 212 typedef struct _ts { 213 /* See Python/ceval.c for comments explaining most fields */ 214 215 struct _ts *prev; 216 struct _ts *next; 217 PyInterpreterState *interp; 218 219 struct _frame *frame; 220 int recursion_depth; 221 char overflowed; /* The stack has overflowed. Allow 50 more calls 222 to handle the runtime error. */ 223 char recursion_critical; /* The current calls must not cause 224 a stack overflow. */ 225 int stackcheck_counter; 226 227 /* 'tracing' keeps track of the execution depth when tracing/profiling. 228 This is to prevent the actual trace/profile code from being recorded in 229 the trace/profile. */ 230 int tracing; 231 int use_tracing; 232 233 Py_tracefunc c_profilefunc; 234 Py_tracefunc c_tracefunc; 235 PyObject *c_profileobj; 236 PyObject *c_traceobj; 237 238 /* The exception currently being raised */ 239 PyObject *curexc_type; 240 PyObject *curexc_value; 241 PyObject *curexc_traceback; 242 243 /* The exception currently being handled, if no coroutines/generators 244 * are present. Always last element on the stack referred to be exc_info. 245 */ 246 _PyErr_StackItem exc_state; 247 248 /* Pointer to the top of the stack of the exceptions currently 249 * being handled */ 250 _PyErr_StackItem *exc_info; 251 252 PyObject *dict; /* Stores per-thread state */ 253 254 int gilstate_counter; 255 256 PyObject *async_exc; /* Asynchronous exception to raise */ 257 unsigned long thread_id; /* Thread id where this tstate was created */ 258 259 int trash_delete_nesting; 260 PyObject *trash_delete_later; 261 262 /* Called when a thread state is deleted normally, but not when it 263 * is destroyed after fork(). 264 * Pain: to prevent rare but fatal shutdown errors (issue 18808), 265 * Thread.join() must wait for the join'ed thread's tstate to be unlinked 266 * from the tstate chain. That happens at the end of a thread's life, 267 * in pystate.c. 268 * The obvious way doesn't quite work: create a lock which the tstate 269 * unlinking code releases, and have Thread.join() wait to acquire that 270 * lock. The problem is that we _are_ at the end of the thread's life: 271 * if the thread holds the last reference to the lock, decref'ing the 272 * lock will delete the lock, and that may trigger arbitrary Python code 273 * if there's a weakref, with a callback, to the lock. But by this time 274 * _PyThreadState_Current is already NULL, so only the simplest of C code 275 * can be allowed to run (in particular it must not be possible to 276 * release the GIL). 277 * So instead of holding the lock directly, the tstate holds a weakref to 278 * the lock: that's the value of on_delete_data below. Decref'ing a 279 * weakref is harmless. 280 * on_delete points to _threadmodule.c's static release_sentinel() function. 281 * After the tstate is unlinked, release_sentinel is called with the 282 * weakref-to-lock (on_delete_data) argument, and release_sentinel releases 283 * the indirectly held lock. 284 */ 285 void (*on_delete)(void *); 286 void *on_delete_data; 287 288 int coroutine_origin_tracking_depth; 289 290 PyObject *coroutine_wrapper; 291 int in_coroutine_wrapper; 292 293 PyObject *async_gen_firstiter; 294 PyObject *async_gen_finalizer; 295 296 PyObject *context; 297 uint64_t context_ver; 298 299 /* Unique thread state id. */ 300 uint64_t id; 301 302 /* XXX signal handlers should also be here */ 303 304 } PyThreadState; 305 #endif /* !Py_LIMITED_API */ 306 307 308 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void); 309 PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *); 310 PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *); 311 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03070000 312 /* New in 3.7 */ 313 PyAPI_FUNC(int64_t) PyInterpreterState_GetID(PyInterpreterState *); 314 #endif 315 #ifndef Py_LIMITED_API 316 PyAPI_FUNC(int) _PyState_AddModule(PyObject*, struct PyModuleDef*); 317 #endif /* !Py_LIMITED_API */ 318 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 319 /* New in 3.3 */ 320 PyAPI_FUNC(int) PyState_AddModule(PyObject*, struct PyModuleDef*); 321 PyAPI_FUNC(int) PyState_RemoveModule(struct PyModuleDef*); 322 #endif 323 PyAPI_FUNC(PyObject*) PyState_FindModule(struct PyModuleDef*); 324 #ifndef Py_LIMITED_API 325 PyAPI_FUNC(void) _PyState_ClearModules(void); 326 #endif 327 328 PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *); 329 #ifndef Py_LIMITED_API 330 PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *); 331 PyAPI_FUNC(void) _PyThreadState_Init(PyThreadState *); 332 #endif /* !Py_LIMITED_API */ 333 PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *); 334 PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *); 335 #ifndef Py_LIMITED_API 336 PyAPI_FUNC(void) _PyThreadState_DeleteExcept(PyThreadState *tstate); 337 #endif /* !Py_LIMITED_API */ 338 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void); 339 #ifndef Py_LIMITED_API 340 PyAPI_FUNC(void) _PyGILState_Reinit(void); 341 #endif /* !Py_LIMITED_API */ 342 343 /* Return the current thread state. The global interpreter lock must be held. 344 * When the current thread state is NULL, this issues a fatal error (so that 345 * the caller needn't check for NULL). */ 346 PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void); 347 348 #ifndef Py_LIMITED_API 349 /* Similar to PyThreadState_Get(), but don't issue a fatal error 350 * if it is NULL. */ 351 PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void); 352 #endif /* !Py_LIMITED_API */ 353 354 PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *); 355 PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void); 356 PyAPI_FUNC(int) PyThreadState_SetAsyncExc(unsigned long, PyObject *); 357 358 359 /* Variable and macro for in-line access to current thread state */ 360 361 /* Assuming the current thread holds the GIL, this is the 362 PyThreadState for the current thread. */ 363 #ifdef Py_BUILD_CORE 364 # define _PyThreadState_Current _PyRuntime.gilstate.tstate_current 365 # define PyThreadState_GET() \ 366 ((PyThreadState*)_Py_atomic_load_relaxed(&_PyThreadState_Current)) 367 #else 368 # define PyThreadState_GET() PyThreadState_Get() 369 #endif 370 371 typedef 372 enum {PyGILState_LOCKED, PyGILState_UNLOCKED} 373 PyGILState_STATE; 374 375 376 /* Ensure that the current thread is ready to call the Python 377 C API, regardless of the current state of Python, or of its 378 thread lock. This may be called as many times as desired 379 by a thread so long as each call is matched with a call to 380 PyGILState_Release(). In general, other thread-state APIs may 381 be used between _Ensure() and _Release() calls, so long as the 382 thread-state is restored to its previous state before the Release(). 383 For example, normal use of the Py_BEGIN_ALLOW_THREADS/ 384 Py_END_ALLOW_THREADS macros are acceptable. 385 386 The return value is an opaque "handle" to the thread state when 387 PyGILState_Ensure() was called, and must be passed to 388 PyGILState_Release() to ensure Python is left in the same state. Even 389 though recursive calls are allowed, these handles can *not* be shared - 390 each unique call to PyGILState_Ensure must save the handle for its 391 call to PyGILState_Release. 392 393 When the function returns, the current thread will hold the GIL. 394 395 Failure is a fatal error. 396 */ 397 PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void); 398 399 /* Release any resources previously acquired. After this call, Python's 400 state will be the same as it was prior to the corresponding 401 PyGILState_Ensure() call (but generally this state will be unknown to 402 the caller, hence the use of the GILState API.) 403 404 Every call to PyGILState_Ensure must be matched by a call to 405 PyGILState_Release on the same thread. 406 */ 407 PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE); 408 409 /* Helper/diagnostic function - get the current thread state for 410 this thread. May return NULL if no GILState API has been used 411 on the current thread. Note that the main thread always has such a 412 thread-state, even if no auto-thread-state call has been made 413 on the main thread. 414 */ 415 PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void); 416 417 #ifndef Py_LIMITED_API 418 /* Helper/diagnostic function - return 1 if the current thread 419 currently holds the GIL, 0 otherwise. 420 421 The function returns 1 if _PyGILState_check_enabled is non-zero. */ 422 PyAPI_FUNC(int) PyGILState_Check(void); 423 424 /* Unsafe function to get the single PyInterpreterState used by this process' 425 GILState implementation. 426 427 Return NULL before _PyGILState_Init() is called and after _PyGILState_Fini() 428 is called. */ 429 PyAPI_FUNC(PyInterpreterState *) _PyGILState_GetInterpreterStateUnsafe(void); 430 #endif /* !Py_LIMITED_API */ 431 432 433 /* The implementation of sys._current_frames() Returns a dict mapping 434 thread id to that thread's current frame. 435 */ 436 #ifndef Py_LIMITED_API 437 PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void); 438 #endif 439 440 /* Routines for advanced debuggers, requested by David Beazley. 441 Don't use unless you know what you are doing! */ 442 #ifndef Py_LIMITED_API 443 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void); 444 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void); 445 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *); 446 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *); 447 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *); 448 449 typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_); 450 #endif 451 452 #ifdef __cplusplus 453 } 454 #endif 455 #endif /* !Py_PYSTATE_H */ 456