python3.13/cpython/pystate.h

0001 #ifndef Py_CPYTHON_PYSTATE_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005
0006 /* private interpreter helpers */
0007
0008 PyAPI_FUNC(int) _PyInterpreterState_RequiresIDRef(PyInterpreterState *);
0009 PyAPI_FUNC(void) _PyInterpreterState_RequireIDRef(PyInterpreterState *, int);
0010
0011 PyAPI_FUNC(PyObject *) PyUnstable_InterpreterState_GetMainModule(PyInterpreterState *);
0012
0013 /* State unique per thread */
0014
0015 /* Py_tracefunc return -1 when raising an exception, or 0 for success. */
0016 typedef int (*Py_tracefunc)(PyObject *, PyFrameObject *, int, PyObject *);
0017
0018 /* The following values are used for 'what' for tracefunc functions
0019  *
0020  * To add a new kind of trace event, also update "trace_init" in
0021  * Python/sysmodule.c to define the Python level event name
0022  */
0023 #define PyTrace_CALL 0
0024 #define PyTrace_EXCEPTION 1
0025 #define PyTrace_LINE 2
0026 #define PyTrace_RETURN 3
0027 #define PyTrace_C_CALL 4
0028 #define PyTrace_C_EXCEPTION 5
0029 #define PyTrace_C_RETURN 6
0030 #define PyTrace_OPCODE 7
0031
0032 typedef struct _err_stackitem {
0033     /* This struct represents a single execution context where we might
0034      * be currently handling an exception.  It is a per-coroutine state
0035      * (coroutine in the computer science sense, including the thread
0036      * and generators).
0037      *
0038      * This is used as an entry on the exception stack, where each
0039      * entry indicates if it is currently handling an exception.
0040      * This ensures that the exception state is not impacted
0041      * by "yields" from an except handler.  The thread
0042      * always has an entry (the bottom-most one).
0043      */
0044
0045     /* The exception currently being handled in this context, if any. */
0046     PyObject *exc_value;
0047
0048     struct _err_stackitem *previous_item;
0049
0050 } _PyErr_StackItem;
0051
0052 typedef struct _stack_chunk {
0053     struct _stack_chunk *previous;
0054     size_t size;
0055     size_t top;
0056     PyObject * data[1]; /* Variable sized */
0057 } _PyStackChunk;
0058
0059 struct _ts {
0060     /* See Python/ceval.c for comments explaining most fields */
0061
0062     PyThreadState *prev;
0063     PyThreadState *next;
0064     PyInterpreterState *interp;
0065
0066     /* The global instrumentation version in high bits, plus flags indicating
0067        when to break out of the interpreter loop in lower bits. See details in
0068        pycore_ceval.h. */
0069     uintptr_t eval_breaker;
0070
0071     struct {
0072         /* Has been initialized to a safe state.
0073
0074            In order to be effective, this must be set to 0 during or right
0075            after allocation. */
0076         unsigned int initialized:1;
0077
0078         /* Has been bound to an OS thread. */
0079         unsigned int bound:1;
0080         /* Has been unbound from its OS thread. */
0081         unsigned int unbound:1;
0082         /* Has been bound aa current for the GILState API. */
0083         unsigned int bound_gilstate:1;
0084         /* Currently in use (maybe holds the GIL). */
0085         unsigned int active:1;
0086         /* Currently holds the GIL. */
0087         unsigned int holds_gil:1;
0088
0089         /* various stages of finalization */
0090         unsigned int finalizing:1;
0091         unsigned int cleared:1;
0092         unsigned int finalized:1;
0093
0094         /* padding to align to 4 bytes */
0095         unsigned int :23;
0096     } _status;
0097 #ifdef Py_BUILD_CORE
0098 #  define _PyThreadState_WHENCE_NOTSET -1
0099 #  define _PyThreadState_WHENCE_UNKNOWN 0
0100 #  define _PyThreadState_WHENCE_INIT 1
0101 #  define _PyThreadState_WHENCE_FINI 2
0102 #  define _PyThreadState_WHENCE_THREADING 3
0103 #  define _PyThreadState_WHENCE_GILSTATE 4
0104 #  define _PyThreadState_WHENCE_EXEC 5
0105 #endif
0106     int _whence;
0107
0108     /* Thread state (_Py_THREAD_ATTACHED, _Py_THREAD_DETACHED, _Py_THREAD_SUSPENDED).
0109        See Include/internal/pycore_pystate.h for more details. */
0110     int state;
0111
0112     int py_recursion_remaining;
0113     int py_recursion_limit;
0114
0115     int c_recursion_remaining;
0116     int recursion_headroom; /* Allow 50 more calls to handle any errors. */
0117
0118     /* 'tracing' keeps track of the execution depth when tracing/profiling.
0119        This is to prevent the actual trace/profile code from being recorded in
0120        the trace/profile. */
0121     int tracing;
0122     int what_event; /* The event currently being monitored, if any. */
0123
0124     /* Pointer to currently executing frame. */
0125     struct _PyInterpreterFrame *current_frame;
0126
0127     Py_tracefunc c_profilefunc;
0128     Py_tracefunc c_tracefunc;
0129     PyObject *c_profileobj;
0130     PyObject *c_traceobj;
0131
0132     /* The exception currently being raised */
0133     PyObject *current_exception;
0134
0135     /* Pointer to the top of the exception stack for the exceptions
0136      * we may be currently handling.  (See _PyErr_StackItem above.)
0137      * This is never NULL. */
0138     _PyErr_StackItem *exc_info;
0139
0140     PyObject *dict;  /* Stores per-thread state */
0141
0142     int gilstate_counter;
0143
0144     PyObject *async_exc; /* Asynchronous exception to raise */
0145     unsigned long thread_id; /* Thread id where this tstate was created */
0146
0147     /* Native thread id where this tstate was created. This will be 0 except on
0148      * those platforms that have the notion of native thread id, for which the
0149      * macro PY_HAVE_THREAD_NATIVE_ID is then defined.
0150      */
0151     unsigned long native_thread_id;
0152
0153     PyObject *delete_later;
0154
0155     /* Tagged pointer to top-most critical section, or zero if there is no
0156      * active critical section. Critical sections are only used in
0157      * `--disable-gil` builds (i.e., when Py_GIL_DISABLED is defined to 1). In the
0158      * default build, this field is always zero.
0159      */
0160     uintptr_t critical_section;
0161
0162     int coroutine_origin_tracking_depth;
0163
0164     PyObject *async_gen_firstiter;
0165     PyObject *async_gen_finalizer;
0166
0167     PyObject *context;
0168     uint64_t context_ver;
0169
0170     /* Unique thread state id. */
0171     uint64_t id;
0172
0173     _PyStackChunk *datastack_chunk;
0174     PyObject **datastack_top;
0175     PyObject **datastack_limit;
0176     /* XXX signal handlers should also be here */
0177
0178     /* The following fields are here to avoid allocation during init.
0179        The data is exposed through PyThreadState pointer fields.
0180        These fields should not be accessed directly outside of init.
0181        This is indicated by an underscore prefix on the field names.
0182
0183        All other PyInterpreterState pointer fields are populated when
0184        needed and default to NULL.
0185        */
0186        // Note some fields do not have a leading underscore for backward
0187        // compatibility.  See https://bugs.python.org/issue45953#msg412046.
0188
0189     /* The thread's exception stack entry.  (Always the last entry.) */
0190     _PyErr_StackItem exc_state;
0191
0192     PyObject *previous_executor;
0193
0194     uint64_t dict_global_version;
0195
0196     /* Used to store/retrieve `threading.local` keys/values for this thread */
0197     PyObject *threading_local_key;
0198
0199     /* Used by `threading.local`s to be remove keys/values for dying threads.
0200        The PyThreadObject must hold the only reference to this value.
0201     */
0202     PyObject *threading_local_sentinel;
0203 };
0204
0205 #ifdef Py_DEBUG
0206    // A debug build is likely built with low optimization level which implies
0207    // higher stack memory usage than a release build: use a lower limit.
0208 #  define Py_C_RECURSION_LIMIT 500
0209 #elif defined(__s390x__)
0210 #  define Py_C_RECURSION_LIMIT 800
0211 #elif defined(_WIN32) && defined(_M_ARM64)
0212 #  define Py_C_RECURSION_LIMIT 1000
0213 #elif defined(_WIN32)
0214 #  define Py_C_RECURSION_LIMIT 3000
0215 #elif defined(__ANDROID__)
0216    // On an ARM64 emulator, API level 34 was OK with 10000, but API level 21
0217    // crashed in test_compiler_recursion_limit.
0218 #  define Py_C_RECURSION_LIMIT 3000
0219 #elif defined(_Py_ADDRESS_SANITIZER)
0220 #  define Py_C_RECURSION_LIMIT 4000
0221 #elif defined(__wasi__)
0222    // Based on wasmtime 16.
0223 #  define Py_C_RECURSION_LIMIT 5000
0224 #else
0225    // This value is duplicated in Lib/test/support/__init__.py
0226 #  define Py_C_RECURSION_LIMIT 10000
0227 #endif
0228
0229
0230 /* other API */
0231
0232 /* Similar to PyThreadState_Get(), but don't issue a fatal error
0233  * if it is NULL. */
0234 PyAPI_FUNC(PyThreadState *) PyThreadState_GetUnchecked(void);
0235
0236 // Alias kept for backward compatibility
0237 #define _PyThreadState_UncheckedGet PyThreadState_GetUnchecked
0238
0239
0240 // Disable tracing and profiling.
0241 PyAPI_FUNC(void) PyThreadState_EnterTracing(PyThreadState *tstate);
0242
0243 // Reset tracing and profiling: enable them if a trace function or a profile
0244 // function is set, otherwise disable them.
0245 PyAPI_FUNC(void) PyThreadState_LeaveTracing(PyThreadState *tstate);
0246
0247 /* PyGILState */
0248
0249 /* Helper/diagnostic function - return 1 if the current thread
0250    currently holds the GIL, 0 otherwise.
0251
0252    The function returns 1 if _PyGILState_check_enabled is non-zero. */
0253 PyAPI_FUNC(int) PyGILState_Check(void);
0254
0255 /* The implementation of sys._current_frames()  Returns a dict mapping
0256    thread id to that thread's current frame.
0257 */
0258 PyAPI_FUNC(PyObject*) _PyThread_CurrentFrames(void);
0259
0260 /* Routines for advanced debuggers, requested by David Beazley.
0261    Don't use unless you know what you are doing! */
0262 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void);
0263 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
0264 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
0265 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
0266 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
0267 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
0268
0269 /* Frame evaluation API */
0270
0271 typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
0272
0273 PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
0274     PyInterpreterState *interp);
0275 PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
0276     PyInterpreterState *interp,
0277     _PyFrameEvalFunction eval_frame);