include/python3.13/pystate.h

0001 /* Thread and interpreter state structures and their interfaces */
0002
0003
0004 #ifndef Py_PYSTATE_H
0005 #define Py_PYSTATE_H
0006 #ifdef __cplusplus
0007 extern "C" {
0008 #endif
0009
0010 /* This limitation is for performance and simplicity. If needed it can be
0011 removed (with effort). */
0012 #define MAX_CO_EXTRA_USERS 255
0013
0014 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void);
0015 PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *);
0016 PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *);
0017
0018 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000
0019 /* New in 3.9 */
0020 /* Get the current interpreter state.
0021
0022    Issue a fatal error if there no current Python thread state or no current
0023    interpreter. It cannot return NULL.
0024
0025    The caller must hold the GIL. */
0026 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Get(void);
0027 #endif
0028
0029 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03080000
0030 /* New in 3.8 */
0031 PyAPI_FUNC(PyObject *) PyInterpreterState_GetDict(PyInterpreterState *);
0032 #endif
0033
0034 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03070000
0035 /* New in 3.7 */
0036 PyAPI_FUNC(int64_t) PyInterpreterState_GetID(PyInterpreterState *);
0037 #endif
0038 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
0039
0040 /* State unique per thread */
0041
0042 /* New in 3.3 */
0043 PyAPI_FUNC(int) PyState_AddModule(PyObject*, PyModuleDef*);
0044 PyAPI_FUNC(int) PyState_RemoveModule(PyModuleDef*);
0045 #endif
0046 PyAPI_FUNC(PyObject*) PyState_FindModule(PyModuleDef*);
0047
0048 PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *);
0049 PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *);
0050 PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *);
0051
0052 /* Get the current thread state.
0053
0054    When the current thread state is NULL, this issues a fatal error (so that
0055    the caller needn't check for NULL).
0056
0057    The caller must hold the GIL.
0058
0059    See also PyThreadState_GetUnchecked() and _PyThreadState_GET(). */
0060 PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void);
0061
0062 // Alias to PyThreadState_Get()
0063 #define PyThreadState_GET() PyThreadState_Get()
0064
0065 PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *);
0066 PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void);
0067 PyAPI_FUNC(int) PyThreadState_SetAsyncExc(unsigned long, PyObject *);
0068
0069 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000
0070 /* New in 3.9 */
0071 PyAPI_FUNC(PyInterpreterState*) PyThreadState_GetInterpreter(PyThreadState *tstate);
0072 PyAPI_FUNC(PyFrameObject*) PyThreadState_GetFrame(PyThreadState *tstate);
0073 PyAPI_FUNC(uint64_t) PyThreadState_GetID(PyThreadState *tstate);
0074 #endif
0075
0076 typedef
0077     enum {PyGILState_LOCKED, PyGILState_UNLOCKED}
0078         PyGILState_STATE;
0079
0080
0081 /* Ensure that the current thread is ready to call the Python
0082    C API, regardless of the current state of Python, or of its
0083    thread lock.  This may be called as many times as desired
0084    by a thread so long as each call is matched with a call to
0085    PyGILState_Release().  In general, other thread-state APIs may
0086    be used between _Ensure() and _Release() calls, so long as the
0087    thread-state is restored to its previous state before the Release().
0088    For example, normal use of the Py_BEGIN_ALLOW_THREADS/
0089    Py_END_ALLOW_THREADS macros are acceptable.
0090
0091    The return value is an opaque "handle" to the thread state when
0092    PyGILState_Ensure() was called, and must be passed to
0093    PyGILState_Release() to ensure Python is left in the same state. Even
0094    though recursive calls are allowed, these handles can *not* be shared -
0095    each unique call to PyGILState_Ensure must save the handle for its
0096    call to PyGILState_Release.
0097
0098    When the function returns, the current thread will hold the GIL.
0099
0100    Failure is a fatal error.
0101 */
0102 PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void);
0103
0104 /* Release any resources previously acquired.  After this call, Python's
0105    state will be the same as it was prior to the corresponding
0106    PyGILState_Ensure() call (but generally this state will be unknown to
0107    the caller, hence the use of the GILState API.)
0108
0109    Every call to PyGILState_Ensure must be matched by a call to
0110    PyGILState_Release on the same thread.
0111 */
0112 PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE);
0113
0114 /* Helper/diagnostic function - get the current thread state for
0115    this thread.  May return NULL if no GILState API has been used
0116    on the current thread.  Note that the main thread always has such a
0117    thread-state, even if no auto-thread-state call has been made
0118    on the main thread.
0119 */
0120 PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void);
0121
0122
0123 #ifndef Py_LIMITED_API
0124 #  define Py_CPYTHON_PYSTATE_H
0125 #  include "cpython/pystate.h"
0126 #  undef Py_CPYTHON_PYSTATE_H
0127 #endif
0128
0129 #ifdef __cplusplus
0130 }
0131 #endif
0132 #endif /* !Py_PYSTATE_H */