venv/Include/pystate.h

   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 /* This limitation is for performance and simplicity. If needed it can be
  12 removed (with effort). */
  13 #define MAX_CO_EXTRA_USERS 255
  14
  15 /* State shared between threads */
  16
  17 struct _ts; /* Forward */
  18 struct _is; /* Forward */
  19 struct _frame; /* Forward declaration for PyFrameObject. */
  20
  21 #ifdef Py_LIMITED_API
  22 typedef struct _is PyInterpreterState;
  23 #else
  24 typedef PyObject* (*_PyFrameEvalFunction)(struct _frame *, int);
  25
  26 typedef struct _is {
  27
  28     struct _is *next;
  29     struct _ts *tstate_head;
  30
  31     PyObject *modules;
  32     PyObject *modules_by_index;
  33     PyObject *sysdict;
  34     PyObject *builtins;
  35     PyObject *importlib;
  36
  37     PyObject *codec_search_path;
  38     PyObject *codec_search_cache;
  39     PyObject *codec_error_registry;
  40     int codecs_initialized;
  41     int fscodec_initialized;
  42
  43 #ifdef HAVE_DLOPEN
  44     int dlopenflags;
  45 #endif
  46
  47     PyObject *builtins_copy;
  48     PyObject *import_func;
  49     /* Initialized to PyEval_EvalFrameDefault(). */
  50     _PyFrameEvalFunction eval_frame;
  51 } PyInterpreterState;
  52 #endif
  53
  54
  55 /* State unique per thread */
  56
  57 #ifndef Py_LIMITED_API
  58 /* Py_tracefunc return -1 when raising an exception, or 0 for success. */
  59 typedef int (*Py_tracefunc)(PyObject *, struct _frame *, int, PyObject *);
  60
  61 /* The following values are used for 'what' for tracefunc functions: */
  62 #define PyTrace_CALL 0
  63 #define PyTrace_EXCEPTION 1
  64 #define PyTrace_LINE 2
  65 #define PyTrace_RETURN 3
  66 #define PyTrace_C_CALL 4
  67 #define PyTrace_C_EXCEPTION 5
  68 #define PyTrace_C_RETURN 6
  69 #endif
  70
  71 #ifdef Py_LIMITED_API
  72 typedef struct _ts PyThreadState;
  73 #else
  74 typedef struct _ts {
  75     /* See Python/ceval.c for comments explaining most fields */
  76
  77     struct _ts *prev;
  78     struct _ts *next;
  79     PyInterpreterState *interp;
  80
  81     struct _frame *frame;
  82     int recursion_depth;
  83     char overflowed; /* The stack has overflowed. Allow 50 more calls
  84                         to handle the runtime error. */
  85     char recursion_critical; /* The current calls must not cause
  86                                 a stack overflow. */
  87     /* 'tracing' keeps track of the execution depth when tracing/profiling.
  88        This is to prevent the actual trace/profile code from being recorded in
  89        the trace/profile. */
  90     int tracing;
  91     int use_tracing;
  92
  93     Py_tracefunc c_profilefunc;
  94     Py_tracefunc c_tracefunc;
  95     PyObject *c_profileobj;
  96     PyObject *c_traceobj;
  97
  98     PyObject *curexc_type;
  99     PyObject *curexc_value;
 100     PyObject *curexc_traceback;
 101
 102     PyObject *exc_type;
 103     PyObject *exc_value;
 104     PyObject *exc_traceback;
 105
 106     PyObject *dict;  /* Stores per-thread state */
 107
 108     int gilstate_counter;
 109
 110     PyObject *async_exc; /* Asynchronous exception to raise */
 111     long thread_id; /* Thread id where this tstate was created */
 112
 113     int trash_delete_nesting;
 114     PyObject *trash_delete_later;
 115
 116     /* Called when a thread state is deleted normally, but not when it
 117      * is destroyed after fork().
 118      * Pain:  to prevent rare but fatal shutdown errors (issue 18808),
 119      * Thread.join() must wait for the join'ed thread's tstate to be unlinked
 120      * from the tstate chain.  That happens at the end of a thread's life,
 121      * in pystate.c.
 122      * The obvious way doesn't quite work:  create a lock which the tstate
 123      * unlinking code releases, and have Thread.join() wait to acquire that
 124      * lock.  The problem is that we _are_ at the end of the thread's life:
 125      * if the thread holds the last reference to the lock, decref'ing the
 126      * lock will delete the lock, and that may trigger arbitrary Python code
 127      * if there's a weakref, with a callback, to the lock.  But by this time
 128      * _PyThreadState_Current is already NULL, so only the simplest of C code
 129      * can be allowed to run (in particular it must not be possible to
 130      * release the GIL).
 131      * So instead of holding the lock directly, the tstate holds a weakref to
 132      * the lock:  that's the value of on_delete_data below.  Decref'ing a
 133      * weakref is harmless.
 134      * on_delete points to _threadmodule.c's static release_sentinel() function.
 135      * After the tstate is unlinked, release_sentinel is called with the
 136      * weakref-to-lock (on_delete_data) argument, and release_sentinel releases
 137      * the indirectly held lock.
 138      */
 139     void (*on_delete)(void *);
 140     void *on_delete_data;
 141
 142     PyObject *coroutine_wrapper;
 143     int in_coroutine_wrapper;
 144
 145     Py_ssize_t co_extra_user_count;
 146     freefunc co_extra_freefuncs[MAX_CO_EXTRA_USERS];
 147
 148     PyObject *async_gen_firstiter;
 149     PyObject *async_gen_finalizer;
 150
 151     /* XXX signal handlers should also be here */
 152
 153 } PyThreadState;
 154 #endif
 155
 156
 157 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void);
 158 PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *);
 159 PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *);
 160 #ifndef Py_LIMITED_API
 161 PyAPI_FUNC(int) _PyState_AddModule(PyObject*, struct PyModuleDef*);
 162 #endif /* !Py_LIMITED_API */
 163 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
 164 /* New in 3.3 */
 165 PyAPI_FUNC(int) PyState_AddModule(PyObject*, struct PyModuleDef*);
 166 PyAPI_FUNC(int) PyState_RemoveModule(struct PyModuleDef*);
 167 #endif
 168 PyAPI_FUNC(PyObject*) PyState_FindModule(struct PyModuleDef*);
 169 #ifndef Py_LIMITED_API
 170 PyAPI_FUNC(void) _PyState_ClearModules(void);
 171 #endif
 172
 173 PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *);
 174 #ifndef Py_LIMITED_API
 175 PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *);
 176 PyAPI_FUNC(void) _PyThreadState_Init(PyThreadState *);
 177 #endif /* !Py_LIMITED_API */
 178 PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *);
 179 PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *);
 180 #ifndef Py_LIMITED_API
 181 PyAPI_FUNC(void) _PyThreadState_DeleteExcept(PyThreadState *tstate);
 182 #endif /* !Py_LIMITED_API */
 183 #ifdef WITH_THREAD
 184 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
 185 #ifndef Py_LIMITED_API
 186 PyAPI_FUNC(void) _PyGILState_Reinit(void);
 187 #endif /* !Py_LIMITED_API */
 188 #endif
 189
 190 /* Return the current thread state. The global interpreter lock must be held.
 191  * When the current thread state is NULL, this issues a fatal error (so that
 192  * the caller needn't check for NULL). */
 193 PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void);
 194
 195 #ifndef Py_LIMITED_API
 196 /* Similar to PyThreadState_Get(), but don't issue a fatal error
 197  * if it is NULL. */
 198 PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void);
 199 #endif /* !Py_LIMITED_API */
 200
 201 PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *);
 202 PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void);
 203 PyAPI_FUNC(int) PyThreadState_SetAsyncExc(long, PyObject *);
 204
 205
 206 /* Variable and macro for in-line access to current thread state */
 207
 208 /* Assuming the current thread holds the GIL, this is the
 209    PyThreadState for the current thread. */
 210 #ifdef Py_BUILD_CORE
 211 PyAPI_DATA(_Py_atomic_address) _PyThreadState_Current;
 212 #  define PyThreadState_GET() \
 213              ((PyThreadState*)_Py_atomic_load_relaxed(&_PyThreadState_Current))
 214 #else
 215 #  define PyThreadState_GET() PyThreadState_Get()
 216 #endif
 217
 218 typedef
 219     enum {PyGILState_LOCKED, PyGILState_UNLOCKED}
 220         PyGILState_STATE;
 221
 222 #ifdef WITH_THREAD
 223
 224 /* Ensure that the current thread is ready to call the Python
 225    C API, regardless of the current state of Python, or of its
 226    thread lock.  This may be called as many times as desired
 227    by a thread so long as each call is matched with a call to
 228    PyGILState_Release().  In general, other thread-state APIs may
 229    be used between _Ensure() and _Release() calls, so long as the
 230    thread-state is restored to its previous state before the Release().
 231    For example, normal use of the Py_BEGIN_ALLOW_THREADS/
 232    Py_END_ALLOW_THREADS macros are acceptable.
 233
 234    The return value is an opaque "handle" to the thread state when
 235    PyGILState_Ensure() was called, and must be passed to
 236    PyGILState_Release() to ensure Python is left in the same state. Even
 237    though recursive calls are allowed, these handles can *not* be shared -
 238    each unique call to PyGILState_Ensure must save the handle for its
 239    call to PyGILState_Release.
 240
 241    When the function returns, the current thread will hold the GIL.
 242
 243    Failure is a fatal error.
 244 */
 245 PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void);
 246
 247 /* Release any resources previously acquired.  After this call, Python's
 248    state will be the same as it was prior to the corresponding
 249    PyGILState_Ensure() call (but generally this state will be unknown to
 250    the caller, hence the use of the GILState API.)
 251
 252    Every call to PyGILState_Ensure must be matched by a call to
 253    PyGILState_Release on the same thread.
 254 */
 255 PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE);
 256
 257 /* Helper/diagnostic function - get the current thread state for
 258    this thread.  May return NULL if no GILState API has been used
 259    on the current thread.  Note that the main thread always has such a
 260    thread-state, even if no auto-thread-state call has been made
 261    on the main thread.
 262 */
 263 PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void);
 264
 265 #ifndef Py_LIMITED_API
 266 /* Issue #26558: Flag to disable PyGILState_Check().
 267    If set to non-zero, PyGILState_Check() always return 1. */
 268 PyAPI_DATA(int) _PyGILState_check_enabled;
 269
 270 /* Helper/diagnostic function - return 1 if the current thread
 271    currently holds the GIL, 0 otherwise.
 272
 273    The function returns 1 if _PyGILState_check_enabled is non-zero. */
 274 PyAPI_FUNC(int) PyGILState_Check(void);
 275
 276 /* Unsafe function to get the single PyInterpreterState used by this process'
 277    GILState implementation.
 278
 279    Return NULL before _PyGILState_Init() is called and after _PyGILState_Fini()
 280    is called. */
 281 PyAPI_FUNC(PyInterpreterState *) _PyGILState_GetInterpreterStateUnsafe(void);
 282 #endif
 283
 284 #endif   /* #ifdef WITH_THREAD */
 285
 286 /* The implementation of sys._current_frames()  Returns a dict mapping
 287    thread id to that thread's current frame.
 288 */
 289 #ifndef Py_LIMITED_API
 290 PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void);
 291 #endif
 292
 293 /* Routines for advanced debuggers, requested by David Beazley.
 294    Don't use unless you know what you are doing! */
 295 #ifndef Py_LIMITED_API
 296 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
 297 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
 298 PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
 299 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
 300
 301 typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_);
 302 #endif
 303
 304 /* hook for PyEval_GetFrame(), requested for Psyco */
 305 #ifndef Py_LIMITED_API
 306 PyAPI_DATA(PyThreadFrameGetter) _PyThreadState_GetFrame;
 307 #endif
 308
 309 #ifdef __cplusplus
 310 }
 311 #endif
 312 #endif /* !Py_PYSTATE_H */