Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2025-01-18 10:06:41

0001 #ifndef Py_CPYTHON_PYSTATE_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004 
0005 
0006 /*
0007 Runtime Feature Flags
0008 
0009 Each flag indicate whether or not a specific runtime feature
0010 is available in a given context.  For example, forking the process
0011 might not be allowed in the current interpreter (i.e. os.fork() would fail).
0012 */
0013 
0014 /* Set if the interpreter share obmalloc runtime state
0015    with the main interpreter. */
0016 #define Py_RTFLAGS_USE_MAIN_OBMALLOC (1UL << 5)
0017 
0018 /* Set if import should check a module for subinterpreter support. */
0019 #define Py_RTFLAGS_MULTI_INTERP_EXTENSIONS (1UL << 8)
0020 
0021 /* Set if threads are allowed. */
0022 #define Py_RTFLAGS_THREADS (1UL << 10)
0023 
0024 /* Set if daemon threads are allowed. */
0025 #define Py_RTFLAGS_DAEMON_THREADS (1UL << 11)
0026 
0027 /* Set if os.fork() is allowed. */
0028 #define Py_RTFLAGS_FORK (1UL << 15)
0029 
0030 /* Set if os.exec*() is allowed. */
0031 #define Py_RTFLAGS_EXEC (1UL << 16)
0032 
0033 
0034 PyAPI_FUNC(int) _PyInterpreterState_HasFeature(PyInterpreterState *interp,
0035                                                unsigned long feature);
0036 
0037 
0038 /* private interpreter helpers */
0039 
0040 PyAPI_FUNC(int) _PyInterpreterState_RequiresIDRef(PyInterpreterState *);
0041 PyAPI_FUNC(void) _PyInterpreterState_RequireIDRef(PyInterpreterState *, int);
0042 
0043 PyAPI_FUNC(PyObject *) _PyInterpreterState_GetMainModule(PyInterpreterState *);
0044 
0045 
0046 /* State unique per thread */
0047 
0048 /* Py_tracefunc return -1 when raising an exception, or 0 for success. */
0049 typedef int (*Py_tracefunc)(PyObject *, PyFrameObject *, int, PyObject *);
0050 
0051 /* The following values are used for 'what' for tracefunc functions
0052  *
0053  * To add a new kind of trace event, also update "trace_init" in
0054  * Python/sysmodule.c to define the Python level event name
0055  */
0056 #define PyTrace_CALL 0
0057 #define PyTrace_EXCEPTION 1
0058 #define PyTrace_LINE 2
0059 #define PyTrace_RETURN 3
0060 #define PyTrace_C_CALL 4
0061 #define PyTrace_C_EXCEPTION 5
0062 #define PyTrace_C_RETURN 6
0063 #define PyTrace_OPCODE 7
0064 
0065 // Internal structure: you should not use it directly, but use public functions
0066 // like PyThreadState_EnterTracing() and PyThreadState_LeaveTracing().
0067 typedef struct _PyCFrame {
0068     /* This struct will be threaded through the C stack
0069      * allowing fast access to per-thread state that needs
0070      * to be accessed quickly by the interpreter, but can
0071      * be modified outside of the interpreter.
0072      *
0073      * WARNING: This makes data on the C stack accessible from
0074      * heap objects. Care must be taken to maintain stack
0075      * discipline and make sure that instances of this struct cannot
0076      * accessed outside of their lifetime.
0077      */
0078     /* Pointer to the currently executing frame (it can be NULL) */
0079     struct _PyInterpreterFrame *current_frame;
0080     struct _PyCFrame *previous;
0081 } _PyCFrame;
0082 
0083 typedef struct _err_stackitem {
0084     /* This struct represents a single execution context where we might
0085      * be currently handling an exception.  It is a per-coroutine state
0086      * (coroutine in the computer science sense, including the thread
0087      * and generators).
0088      *
0089      * This is used as an entry on the exception stack, where each
0090      * entry indicates if it is currently handling an exception.
0091      * This ensures that the exception state is not impacted
0092      * by "yields" from an except handler.  The thread
0093      * always has an entry (the bottom-most one).
0094      */
0095 
0096     /* The exception currently being handled in this context, if any. */
0097     PyObject *exc_value;
0098 
0099     struct _err_stackitem *previous_item;
0100 
0101 } _PyErr_StackItem;
0102 
0103 typedef struct _stack_chunk {
0104     struct _stack_chunk *previous;
0105     size_t size;
0106     size_t top;
0107     PyObject * data[1]; /* Variable sized */
0108 } _PyStackChunk;
0109 
0110 struct _py_trashcan {
0111     int delete_nesting;
0112     PyObject *delete_later;
0113 };
0114 
0115 struct _ts {
0116     /* See Python/ceval.c for comments explaining most fields */
0117 
0118     PyThreadState *prev;
0119     PyThreadState *next;
0120     PyInterpreterState *interp;
0121 
0122     struct {
0123         /* Has been initialized to a safe state.
0124 
0125            In order to be effective, this must be set to 0 during or right
0126            after allocation. */
0127         unsigned int initialized:1;
0128 
0129         /* Has been bound to an OS thread. */
0130         unsigned int bound:1;
0131         /* Has been unbound from its OS thread. */
0132         unsigned int unbound:1;
0133         /* Has been bound aa current for the GILState API. */
0134         unsigned int bound_gilstate:1;
0135         /* Currently in use (maybe holds the GIL). */
0136         unsigned int active:1;
0137 
0138         /* various stages of finalization */
0139         unsigned int finalizing:1;
0140         unsigned int cleared:1;
0141         unsigned int finalized:1;
0142 
0143         /* padding to align to 4 bytes */
0144         unsigned int :24;
0145     } _status;
0146 
0147     int py_recursion_remaining;
0148     int py_recursion_limit;
0149 
0150     int c_recursion_remaining;
0151     int recursion_headroom; /* Allow 50 more calls to handle any errors. */
0152 
0153     /* 'tracing' keeps track of the execution depth when tracing/profiling.
0154        This is to prevent the actual trace/profile code from being recorded in
0155        the trace/profile. */
0156     int tracing;
0157     int what_event; /* The event currently being monitored, if any. */
0158 
0159     /* Pointer to current _PyCFrame in the C stack frame of the currently,
0160      * or most recently, executing _PyEval_EvalFrameDefault. */
0161     _PyCFrame *cframe;
0162 
0163     Py_tracefunc c_profilefunc;
0164     Py_tracefunc c_tracefunc;
0165     PyObject *c_profileobj;
0166     PyObject *c_traceobj;
0167 
0168     /* The exception currently being raised */
0169     PyObject *current_exception;
0170 
0171     /* Pointer to the top of the exception stack for the exceptions
0172      * we may be currently handling.  (See _PyErr_StackItem above.)
0173      * This is never NULL. */
0174     _PyErr_StackItem *exc_info;
0175 
0176     PyObject *dict;  /* Stores per-thread state */
0177 
0178     int gilstate_counter;
0179 
0180     PyObject *async_exc; /* Asynchronous exception to raise */
0181     unsigned long thread_id; /* Thread id where this tstate was created */
0182 
0183     /* Native thread id where this tstate was created. This will be 0 except on
0184      * those platforms that have the notion of native thread id, for which the
0185      * macro PY_HAVE_THREAD_NATIVE_ID is then defined.
0186      */
0187     unsigned long native_thread_id;
0188 
0189     struct _py_trashcan trash;
0190 
0191     /* Called when a thread state is deleted normally, but not when it
0192      * is destroyed after fork().
0193      * Pain:  to prevent rare but fatal shutdown errors (issue 18808),
0194      * Thread.join() must wait for the join'ed thread's tstate to be unlinked
0195      * from the tstate chain.  That happens at the end of a thread's life,
0196      * in pystate.c.
0197      * The obvious way doesn't quite work:  create a lock which the tstate
0198      * unlinking code releases, and have Thread.join() wait to acquire that
0199      * lock.  The problem is that we _are_ at the end of the thread's life:
0200      * if the thread holds the last reference to the lock, decref'ing the
0201      * lock will delete the lock, and that may trigger arbitrary Python code
0202      * if there's a weakref, with a callback, to the lock.  But by this time
0203      * _PyRuntime.gilstate.tstate_current is already NULL, so only the simplest
0204      * of C code can be allowed to run (in particular it must not be possible to
0205      * release the GIL).
0206      * So instead of holding the lock directly, the tstate holds a weakref to
0207      * the lock:  that's the value of on_delete_data below.  Decref'ing a
0208      * weakref is harmless.
0209      * on_delete points to _threadmodule.c's static release_sentinel() function.
0210      * After the tstate is unlinked, release_sentinel is called with the
0211      * weakref-to-lock (on_delete_data) argument, and release_sentinel releases
0212      * the indirectly held lock.
0213      */
0214     void (*on_delete)(void *);
0215     void *on_delete_data;
0216 
0217     int coroutine_origin_tracking_depth;
0218 
0219     PyObject *async_gen_firstiter;
0220     PyObject *async_gen_finalizer;
0221 
0222     PyObject *context;
0223     uint64_t context_ver;
0224 
0225     /* Unique thread state id. */
0226     uint64_t id;
0227 
0228     _PyStackChunk *datastack_chunk;
0229     PyObject **datastack_top;
0230     PyObject **datastack_limit;
0231     /* XXX signal handlers should also be here */
0232 
0233     /* The following fields are here to avoid allocation during init.
0234        The data is exposed through PyThreadState pointer fields.
0235        These fields should not be accessed directly outside of init.
0236        This is indicated by an underscore prefix on the field names.
0237 
0238        All other PyInterpreterState pointer fields are populated when
0239        needed and default to NULL.
0240        */
0241        // Note some fields do not have a leading underscore for backward
0242        // compatibility.  See https://bugs.python.org/issue45953#msg412046.
0243 
0244     /* The thread's exception stack entry.  (Always the last entry.) */
0245     _PyErr_StackItem exc_state;
0246 
0247     /* The bottom-most frame on the stack. */
0248     _PyCFrame root_cframe;
0249 };
0250 
0251 /* WASI has limited call stack. Python's recursion limit depends on code
0252    layout, optimization, and WASI runtime. Wasmtime can handle about 700
0253    recursions, sometimes less. 500 is a more conservative limit. */
0254 #ifdef Py_DEBUG
0255 #  if defined(__wasi__)
0256 #    define C_RECURSION_LIMIT 150
0257 #  else
0258 #    define C_RECURSION_LIMIT 500
0259 #  endif
0260 #else
0261 #  if defined(__wasi__)
0262 #    define C_RECURSION_LIMIT 500
0263 #  elif defined(__s390x__)
0264 #    define C_RECURSION_LIMIT 800
0265 #  elif defined(_WIN32)
0266 #    define C_RECURSION_LIMIT 3000
0267 #  elif defined(_Py_ADDRESS_SANITIZER)
0268 #    define C_RECURSION_LIMIT 4000
0269 #  else
0270      // This value is duplicated in Lib/test/support/__init__.py
0271 #    define C_RECURSION_LIMIT 10000
0272 #  endif
0273 #endif
0274 
0275 /* other API */
0276 
0277 // Alias for backward compatibility with Python 3.8
0278 #define _PyInterpreterState_Get PyInterpreterState_Get
0279 
0280 /* An alias for the internal _PyThreadState_New(),
0281    kept for stable ABI compatibility. */
0282 PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *);
0283 
0284 /* Similar to PyThreadState_Get(), but don't issue a fatal error
0285  * if it is NULL. */
0286 PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void);
0287 
0288 PyAPI_FUNC(PyObject *) _PyThreadState_GetDict(PyThreadState *tstate);
0289 
0290 // Disable tracing and profiling.
0291 PyAPI_FUNC(void) PyThreadState_EnterTracing(PyThreadState *tstate);
0292 
0293 // Reset tracing and profiling: enable them if a trace function or a profile
0294 // function is set, otherwise disable them.
0295 PyAPI_FUNC(void) PyThreadState_LeaveTracing(PyThreadState *tstate);
0296 
0297 /* PyGILState */
0298 
0299 /* Helper/diagnostic function - return 1 if the current thread
0300    currently holds the GIL, 0 otherwise.
0301 
0302    The function returns 1 if _PyGILState_check_enabled is non-zero. */
0303 PyAPI_FUNC(int) PyGILState_Check(void);
0304 
0305 /* Get the single PyInterpreterState used by this process' GILState
0306    implementation.
0307 
0308    This function doesn't check for error. Return NULL before _PyGILState_Init()
0309    is called and after _PyGILState_Fini() is called.
0310 
0311    See also _PyInterpreterState_Get() and _PyInterpreterState_GET(). */
0312 PyAPI_FUNC(PyInterpreterState *) _PyGILState_GetInterpreterStateUnsafe(void);
0313 
0314 /* The implementation of sys._current_frames()  Returns a dict mapping
0315    thread id to that thread's current frame.
0316 */
0317 PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void);
0318 
0319 /* The implementation of sys._current_exceptions()  Returns a dict mapping
0320    thread id to that thread's current exception.
0321 */
0322 PyAPI_FUNC(PyObject *) _PyThread_CurrentExceptions(void);
0323 
0324 /* Routines for advanced debuggers, requested by David Beazley.
0325    Don't use unless you know what you are doing! */
0326 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Main(void);
0327 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
0328 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
0329 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
0330 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
0331 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
0332 
0333 /* Frame evaluation API */
0334 
0335 typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
0336 
0337 PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
0338     PyInterpreterState *interp);
0339 PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
0340     PyInterpreterState *interp,
0341     _PyFrameEvalFunction eval_frame);
0342 
0343 PyAPI_FUNC(const PyConfig*) _PyInterpreterState_GetConfig(PyInterpreterState *interp);
0344 
0345 /* Get a copy of the current interpreter configuration.
0346 
0347    Return 0 on success. Raise an exception and return -1 on error.
0348 
0349    The caller must initialize 'config', using PyConfig_InitPythonConfig()
0350    for example.
0351 
0352    Python must be preinitialized to call this method.
0353    The caller must hold the GIL.
0354 
0355    Once done with the configuration, PyConfig_Clear() must be called to clear
0356    it. */
0357 PyAPI_FUNC(int) _PyInterpreterState_GetConfigCopy(
0358     struct PyConfig *config);
0359 
0360 /* Set the configuration of the current interpreter.
0361 
0362    This function should be called during or just after the Python
0363    initialization.
0364 
0365    Update the sys module with the new configuration. If the sys module was
0366    modified directly after the Python initialization, these changes are lost.
0367 
0368    Some configuration like faulthandler or warnoptions can be updated in the
0369    configuration, but don't reconfigure Python (don't enable/disable
0370    faulthandler and don't reconfigure warnings filters).
0371 
0372    Return 0 on success. Raise an exception and return -1 on error.
0373 
0374    The configuration should come from _PyInterpreterState_GetConfigCopy(). */
0375 PyAPI_FUNC(int) _PyInterpreterState_SetConfig(
0376     const struct PyConfig *config);
0377 
0378 // Get the configuration of the current interpreter.
0379 // The caller must hold the GIL.
0380 PyAPI_FUNC(const PyConfig*) _Py_GetConfig(void);
0381 
0382 
0383 /* cross-interpreter data */
0384 
0385 // _PyCrossInterpreterData is similar to Py_buffer as an effectively
0386 // opaque struct that holds data outside the object machinery.  This
0387 // is necessary to pass safely between interpreters in the same process.
0388 typedef struct _xid _PyCrossInterpreterData;
0389 
0390 typedef PyObject *(*xid_newobjectfunc)(_PyCrossInterpreterData *);
0391 typedef void (*xid_freefunc)(void *);
0392 
0393 struct _xid {
0394     // data is the cross-interpreter-safe derivation of a Python object
0395     // (see _PyObject_GetCrossInterpreterData).  It will be NULL if the
0396     // new_object func (below) encodes the data.
0397     void *data;
0398     // obj is the Python object from which the data was derived.  This
0399     // is non-NULL only if the data remains bound to the object in some
0400     // way, such that the object must be "released" (via a decref) when
0401     // the data is released.  In that case the code that sets the field,
0402     // likely a registered "crossinterpdatafunc", is responsible for
0403     // ensuring it owns the reference (i.e. incref).
0404     PyObject *obj;
0405     // interp is the ID of the owning interpreter of the original
0406     // object.  It corresponds to the active interpreter when
0407     // _PyObject_GetCrossInterpreterData() was called.  This should only
0408     // be set by the cross-interpreter machinery.
0409     //
0410     // We use the ID rather than the PyInterpreterState to avoid issues
0411     // with deleted interpreters.  Note that IDs are never re-used, so
0412     // each one will always correspond to a specific interpreter
0413     // (whether still alive or not).
0414     int64_t interp;
0415     // new_object is a function that returns a new object in the current
0416     // interpreter given the data.  The resulting object (a new
0417     // reference) will be equivalent to the original object.  This field
0418     // is required.
0419     xid_newobjectfunc new_object;
0420     // free is called when the data is released.  If it is NULL then
0421     // nothing will be done to free the data.  For some types this is
0422     // okay (e.g. bytes) and for those types this field should be set
0423     // to NULL.  However, for most the data was allocated just for
0424     // cross-interpreter use, so it must be freed when
0425     // _PyCrossInterpreterData_Release is called or the memory will
0426     // leak.  In that case, at the very least this field should be set
0427     // to PyMem_RawFree (the default if not explicitly set to NULL).
0428     // The call will happen with the original interpreter activated.
0429     xid_freefunc free;
0430 };
0431 
0432 PyAPI_FUNC(void) _PyCrossInterpreterData_Init(
0433         _PyCrossInterpreterData *data,
0434         PyInterpreterState *interp, void *shared, PyObject *obj,
0435         xid_newobjectfunc new_object);
0436 PyAPI_FUNC(int) _PyCrossInterpreterData_InitWithSize(
0437         _PyCrossInterpreterData *,
0438         PyInterpreterState *interp, const size_t, PyObject *,
0439         xid_newobjectfunc);
0440 PyAPI_FUNC(void) _PyCrossInterpreterData_Clear(
0441         PyInterpreterState *, _PyCrossInterpreterData *);
0442 
0443 PyAPI_FUNC(int) _PyObject_GetCrossInterpreterData(PyObject *, _PyCrossInterpreterData *);
0444 PyAPI_FUNC(PyObject *) _PyCrossInterpreterData_NewObject(_PyCrossInterpreterData *);
0445 PyAPI_FUNC(int) _PyCrossInterpreterData_Release(_PyCrossInterpreterData *);
0446 
0447 PyAPI_FUNC(int) _PyObject_CheckCrossInterpreterData(PyObject *);
0448 
0449 /* cross-interpreter data registry */
0450 
0451 typedef int (*crossinterpdatafunc)(PyThreadState *tstate, PyObject *,
0452                                    _PyCrossInterpreterData *);
0453 
0454 PyAPI_FUNC(int) _PyCrossInterpreterData_RegisterClass(PyTypeObject *, crossinterpdatafunc);
0455 PyAPI_FUNC(int) _PyCrossInterpreterData_UnregisterClass(PyTypeObject *);
0456 PyAPI_FUNC(crossinterpdatafunc) _PyCrossInterpreterData_Lookup(PyObject *);