jpayne@69: /* Thread and interpreter state structures and their interfaces */ jpayne@69: jpayne@69: jpayne@69: #ifndef Py_PYSTATE_H jpayne@69: #define Py_PYSTATE_H jpayne@69: #ifdef __cplusplus jpayne@69: extern "C" { jpayne@69: #endif jpayne@69: jpayne@69: #include "pythread.h" jpayne@69: jpayne@69: /* This limitation is for performance and simplicity. If needed it can be jpayne@69: removed (with effort). */ jpayne@69: #define MAX_CO_EXTRA_USERS 255 jpayne@69: jpayne@69: /* Forward declarations for PyFrameObject, PyThreadState jpayne@69: and PyInterpreterState */ jpayne@69: struct _frame; jpayne@69: struct _ts; jpayne@69: struct _is; jpayne@69: jpayne@69: /* struct _ts is defined in cpython/pystate.h */ jpayne@69: typedef struct _ts PyThreadState; jpayne@69: /* struct _is is defined in internal/pycore_pystate.h */ jpayne@69: typedef struct _is PyInterpreterState; jpayne@69: jpayne@69: PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void); jpayne@69: PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *); jpayne@69: PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *); jpayne@69: jpayne@69: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03080000 jpayne@69: /* New in 3.8 */ jpayne@69: PyAPI_FUNC(PyObject *) PyInterpreterState_GetDict(PyInterpreterState *); jpayne@69: #endif jpayne@69: jpayne@69: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03070000 jpayne@69: /* New in 3.7 */ jpayne@69: PyAPI_FUNC(int64_t) PyInterpreterState_GetID(PyInterpreterState *); jpayne@69: #endif jpayne@69: #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 jpayne@69: jpayne@69: /* State unique per thread */ jpayne@69: jpayne@69: /* New in 3.3 */ jpayne@69: PyAPI_FUNC(int) PyState_AddModule(PyObject*, struct PyModuleDef*); jpayne@69: PyAPI_FUNC(int) PyState_RemoveModule(struct PyModuleDef*); jpayne@69: #endif jpayne@69: PyAPI_FUNC(PyObject*) PyState_FindModule(struct PyModuleDef*); jpayne@69: jpayne@69: PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *); jpayne@69: PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *); jpayne@69: PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *); jpayne@69: PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void); jpayne@69: jpayne@69: /* Get the current thread state. jpayne@69: jpayne@69: When the current thread state is NULL, this issues a fatal error (so that jpayne@69: the caller needn't check for NULL). jpayne@69: jpayne@69: The caller must hold the GIL. jpayne@69: jpayne@69: See also PyThreadState_GET() and _PyThreadState_GET(). */ jpayne@69: PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void); jpayne@69: jpayne@69: /* Get the current Python thread state. jpayne@69: jpayne@69: Macro using PyThreadState_Get() or _PyThreadState_GET() depending if jpayne@69: pycore_pystate.h is included or not (this header redefines the macro). jpayne@69: jpayne@69: If PyThreadState_Get() is used, issue a fatal error if the current thread jpayne@69: state is NULL. jpayne@69: jpayne@69: See also PyThreadState_Get() and _PyThreadState_GET(). */ jpayne@69: #define PyThreadState_GET() PyThreadState_Get() jpayne@69: jpayne@69: PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *); jpayne@69: PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void); jpayne@69: PyAPI_FUNC(int) PyThreadState_SetAsyncExc(unsigned long, PyObject *); jpayne@69: jpayne@69: typedef jpayne@69: enum {PyGILState_LOCKED, PyGILState_UNLOCKED} jpayne@69: PyGILState_STATE; jpayne@69: jpayne@69: jpayne@69: /* Ensure that the current thread is ready to call the Python jpayne@69: C API, regardless of the current state of Python, or of its jpayne@69: thread lock. This may be called as many times as desired jpayne@69: by a thread so long as each call is matched with a call to jpayne@69: PyGILState_Release(). In general, other thread-state APIs may jpayne@69: be used between _Ensure() and _Release() calls, so long as the jpayne@69: thread-state is restored to its previous state before the Release(). jpayne@69: For example, normal use of the Py_BEGIN_ALLOW_THREADS/ jpayne@69: Py_END_ALLOW_THREADS macros are acceptable. jpayne@69: jpayne@69: The return value is an opaque "handle" to the thread state when jpayne@69: PyGILState_Ensure() was called, and must be passed to jpayne@69: PyGILState_Release() to ensure Python is left in the same state. Even jpayne@69: though recursive calls are allowed, these handles can *not* be shared - jpayne@69: each unique call to PyGILState_Ensure must save the handle for its jpayne@69: call to PyGILState_Release. jpayne@69: jpayne@69: When the function returns, the current thread will hold the GIL. jpayne@69: jpayne@69: Failure is a fatal error. jpayne@69: */ jpayne@69: PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void); jpayne@69: jpayne@69: /* Release any resources previously acquired. After this call, Python's jpayne@69: state will be the same as it was prior to the corresponding jpayne@69: PyGILState_Ensure() call (but generally this state will be unknown to jpayne@69: the caller, hence the use of the GILState API.) jpayne@69: jpayne@69: Every call to PyGILState_Ensure must be matched by a call to jpayne@69: PyGILState_Release on the same thread. jpayne@69: */ jpayne@69: PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE); jpayne@69: jpayne@69: /* Helper/diagnostic function - get the current thread state for jpayne@69: this thread. May return NULL if no GILState API has been used jpayne@69: on the current thread. Note that the main thread always has such a jpayne@69: thread-state, even if no auto-thread-state call has been made jpayne@69: on the main thread. jpayne@69: */ jpayne@69: PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void); jpayne@69: jpayne@69: jpayne@69: #ifndef Py_LIMITED_API jpayne@69: # define Py_CPYTHON_PYSTATE_H jpayne@69: # include "cpython/pystate.h" jpayne@69: # undef Py_CPYTHON_PYSTATE_H jpayne@69: #endif jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: } jpayne@69: #endif jpayne@69: #endif /* !Py_PYSTATE_H */