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 /* Borrowed reference to the current frame (it can be NULL) */ 220 struct _frame *frame; 221 int recursion_depth; 222 char overflowed; /* The stack has overflowed. Allow 50 more calls 223 to handle the runtime error. */ 224 char recursion_critical; /* The current calls must not cause 225 a stack overflow. */ 226 int stackcheck_counter; 227 228 /* 'tracing' keeps track of the execution depth when tracing/profiling. 229 This is to prevent the actual trace/profile code from being recorded in 230 the trace/profile. */ 231 int tracing; 232 int use_tracing; 233 234 Py_tracefunc c_profilefunc; 235 Py_tracefunc c_tracefunc; 236 PyObject *c_profileobj; 237 PyObject *c_traceobj; 238 239 /* The exception currently being raised */ 240 PyObject *curexc_type; 241 PyObject *curexc_value; 242 PyObject *curexc_traceback; 243 244 /* The exception currently being handled, if no coroutines/generators 245 * are present. Always last element on the stack referred to be exc_info. 246 */ 247 _PyErr_StackItem exc_state; 248 249 /* Pointer to the top of the stack of the exceptions currently 250 * being handled */ 251 _PyErr_StackItem *exc_info; 252 253 PyObject *dict; /* Stores per-thread state */ 254 255 int gilstate_counter; 256 257 PyObject *async_exc; /* Asynchronous exception to raise */ 258 unsigned long thread_id; /* Thread id where this tstate was created */ 259 260 int trash_delete_nesting; 261 PyObject *trash_delete_later; 262 263 /* Called when a thread state is deleted normally, but not when it 264 * is destroyed after fork(). 265 * Pain: to prevent rare but fatal shutdown errors (issue 18808), 266 * Thread.join() must wait for the join'ed thread's tstate to be unlinked 267 * from the tstate chain. That happens at the end of a thread's life, 268 * in pystate.c. 269 * The obvious way doesn't quite work: create a lock which the tstate 270 * unlinking code releases, and have Thread.join() wait to acquire that 271 * lock. The problem is that we _are_ at the end of the thread's life: 272 * if the thread holds the last reference to the lock, decref'ing the 273 * lock will delete the lock, and that may trigger arbitrary Python code 274 * if there's a weakref, with a callback, to the lock. But by this time 275 * _PyThreadState_Current is already NULL, so only the simplest of C code 276 * can be allowed to run (in particular it must not be possible to 277 * release the GIL). 278 * So instead of holding the lock directly, the tstate holds a weakref to 279 * the lock: that's the value of on_delete_data below. Decref'ing a 280 * weakref is harmless. 281 * on_delete points to _threadmodule.c's static release_sentinel() function. 282 * After the tstate is unlinked, release_sentinel is called with the 283 * weakref-to-lock (on_delete_data) argument, and release_sentinel releases 284 * the indirectly held lock. 285 */ 286 void (*on_delete)(void *); 287 void *on_delete_data; 288 289 int coroutine_origin_tracking_depth; 290 291 PyObject *coroutine_wrapper; 292 int in_coroutine_wrapper; 293 294 PyObject *async_gen_firstiter; 295 PyObject *async_gen_finalizer; 296 297 PyObject *context; 298 uint64_t context_ver; 299 300 /* Unique thread state id. */ 301 uint64_t id; 302 303 /* XXX signal handlers should also be here */ 304 305 } PyThreadState; 306 #endif /* !Py_LIMITED_API */ 307 308 309 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void); 310 PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *); 311 PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *); 312 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03070000 313 /* New in 3.7 */ 314 PyAPI_FUNC(int64_t) PyInterpreterState_GetID(PyInterpreterState *); 315 #endif 316 #ifndef Py_LIMITED_API 317 PyAPI_FUNC(int) _PyState_AddModule(PyObject*, struct PyModuleDef*); 318 #endif /* !Py_LIMITED_API */ 319 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 320 /* New in 3.3 */ 321 PyAPI_FUNC(int) PyState_AddModule(PyObject*, struct PyModuleDef*); 322 PyAPI_FUNC(int) PyState_RemoveModule(struct PyModuleDef*); 323 #endif 324 PyAPI_FUNC(PyObject*) PyState_FindModule(struct PyModuleDef*); 325 #ifndef Py_LIMITED_API 326 PyAPI_FUNC(void) _PyState_ClearModules(void); 327 #endif 328 329 PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *); 330 #ifndef Py_LIMITED_API 331 PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *); 332 PyAPI_FUNC(void) _PyThreadState_Init(PyThreadState *); 333 #endif /* !Py_LIMITED_API */ 334 PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *); 335 PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *); 336 #ifndef Py_LIMITED_API 337 PyAPI_FUNC(void) _PyThreadState_DeleteExcept(PyThreadState *tstate); 338 #endif /* !Py_LIMITED_API */ 339 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void); 340 #ifndef Py_LIMITED_API 341 PyAPI_FUNC(void) _PyGILState_Reinit(void); 342 #endif /* !Py_LIMITED_API */ 343 344 /* Return the current thread state. The global interpreter lock must be held. 345 * When the current thread state is NULL, this issues a fatal error (so that 346 * the caller needn't check for NULL). */ 347 PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void); 348 349 #ifndef Py_LIMITED_API 350 /* Similar to PyThreadState_Get(), but don't issue a fatal error 351 * if it is NULL. */ 352 PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void); 353 #endif /* !Py_LIMITED_API */ 354 355 PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *); 356 PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void); 357 PyAPI_FUNC(int) PyThreadState_SetAsyncExc(unsigned long, PyObject *); 358 359 360 /* Variable and macro for in-line access to current thread state */ 361 362 /* Assuming the current thread holds the GIL, this is the 363 PyThreadState for the current thread. */ 364 #ifdef Py_BUILD_CORE 365 # define _PyThreadState_Current _PyRuntime.gilstate.tstate_current 366 # define PyThreadState_GET() \ 367 ((PyThreadState*)_Py_atomic_load_relaxed(&_PyThreadState_Current)) 368 #else 369 # define PyThreadState_GET() PyThreadState_Get() 370 #endif 371 372 typedef 373 enum {PyGILState_LOCKED, PyGILState_UNLOCKED} 374 PyGILState_STATE; 375 376 377 /* Ensure that the current thread is ready to call the Python 378 C API, regardless of the current state of Python, or of its 379 thread lock. This may be called as many times as desired 380 by a thread so long as each call is matched with a call to 381 PyGILState_Release(). In general, other thread-state APIs may 382 be used between _Ensure() and _Release() calls, so long as the 383 thread-state is restored to its previous state before the Release(). 384 For example, normal use of the Py_BEGIN_ALLOW_THREADS/ 385 Py_END_ALLOW_THREADS macros are acceptable. 386 387 The return value is an opaque "handle" to the thread state when 388 PyGILState_Ensure() was called, and must be passed to 389 PyGILState_Release() to ensure Python is left in the same state. Even 390 though recursive calls are allowed, these handles can *not* be shared - 391 each unique call to PyGILState_Ensure must save the handle for its 392 call to PyGILState_Release. 393 394 When the function returns, the current thread will hold the GIL. 395 396 Failure is a fatal error. 397 */ 398 PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void); 399 400 /* Release any resources previously acquired. After this call, Python's 401 state will be the same as it was prior to the corresponding 402 PyGILState_Ensure() call (but generally this state will be unknown to 403 the caller, hence the use of the GILState API.) 404 405 Every call to PyGILState_Ensure must be matched by a call to 406 PyGILState_Release on the same thread. 407 */ 408 PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE); 409 410 /* Helper/diagnostic function - get the current thread state for 411 this thread. May return NULL if no GILState API has been used 412 on the current thread. Note that the main thread always has such a 413 thread-state, even if no auto-thread-state call has been made 414 on the main thread. 415 */ 416 PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void); 417 418 #ifndef Py_LIMITED_API 419 /* Helper/diagnostic function - return 1 if the current thread 420 currently holds the GIL, 0 otherwise. 421 422 The function returns 1 if _PyGILState_check_enabled is non-zero. */ 423 PyAPI_FUNC(int) PyGILState_Check(void); 424 425 /* Unsafe function to get the single PyInterpreterState used by this process' 426 GILState implementation. 427 428 Return NULL before _PyGILState_Init() is called and after _PyGILState_Fini() 429 is called. */ 430 PyAPI_FUNC(PyInterpreterState *) _PyGILState_GetInterpreterStateUnsafe(void); 431 #endif /* !Py_LIMITED_API */ 432 433 434 /* The implementation of sys._current_frames() Returns a dict mapping 435 thread id to that thread's current frame. 436 */ 437 #ifndef Py_LIMITED_API 438 PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void); 439 #endif 440 441 /* Routines for advanced debuggers, requested by David Beazley. 442 Don't use unless you know what you are doing! */ 443 #ifndef Py_LIMITED_API 444 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void); 445 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void); 446 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *); 447 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *); 448 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *); 449 450 typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_); 451 #endif 452 453 #ifdef __cplusplus 454 } 455 #endif 456 #endif /* !Py_PYSTATE_H */ 457