1 /* Thread and interpreter state structures and their interfaces */ 2 3 4 #ifndef Py_PYSTATE_H 5 #define Py_PYSTATE_H 6 #ifdef __cplusplus 7 extern "C" { 8 #endif 9 10 /* This limitation is for performance and simplicity. If needed it can be 11 removed (with effort). */ 12 #define MAX_CO_EXTRA_USERS 255 13 14 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void); 15 PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *); 16 PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *); 17 18 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000 19 /* New in 3.9 */ 20 /* Get the current interpreter state. 21 22 Issue a fatal error if there no current Python thread state or no current 23 interpreter. It cannot return NULL. 24 25 The caller must hold the GIL. */ 26 PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Get(void); 27 #endif 28 29 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03080000 30 /* New in 3.8 */ 31 PyAPI_FUNC(PyObject *) PyInterpreterState_GetDict(PyInterpreterState *); 32 #endif 33 34 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03070000 35 /* New in 3.7 */ 36 PyAPI_FUNC(int64_t) PyInterpreterState_GetID(PyInterpreterState *); 37 #endif 38 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 39 40 /* State unique per thread */ 41 42 /* New in 3.3 */ 43 PyAPI_FUNC(int) PyState_AddModule(PyObject*, PyModuleDef*); 44 PyAPI_FUNC(int) PyState_RemoveModule(PyModuleDef*); 45 #endif 46 PyAPI_FUNC(PyObject*) PyState_FindModule(PyModuleDef*); 47 48 PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *); 49 PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *); 50 PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *); 51 52 /* Get the current thread state. 53 54 When the current thread state is NULL, this issues a fatal error (so that 55 the caller needn't check for NULL). 56 57 The caller must hold the GIL. 58 59 See also _PyThreadState_UncheckedGet() and _PyThreadState_GET(). */ 60 PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void); 61 62 // Alias to PyThreadState_Get() 63 #define PyThreadState_GET() PyThreadState_Get() 64 65 PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *); 66 PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void); 67 PyAPI_FUNC(int) PyThreadState_SetAsyncExc(unsigned long, PyObject *); 68 69 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000 70 /* New in 3.9 */ 71 PyAPI_FUNC(PyInterpreterState*) PyThreadState_GetInterpreter(PyThreadState *tstate); 72 PyAPI_FUNC(PyFrameObject*) PyThreadState_GetFrame(PyThreadState *tstate); 73 PyAPI_FUNC(uint64_t) PyThreadState_GetID(PyThreadState *tstate); 74 #endif 75 76 typedef 77 enum {PyGILState_LOCKED, PyGILState_UNLOCKED} 78 PyGILState_STATE; 79 80 81 /* Ensure that the current thread is ready to call the Python 82 C API, regardless of the current state of Python, or of its 83 thread lock. This may be called as many times as desired 84 by a thread so long as each call is matched with a call to 85 PyGILState_Release(). In general, other thread-state APIs may 86 be used between _Ensure() and _Release() calls, so long as the 87 thread-state is restored to its previous state before the Release(). 88 For example, normal use of the Py_BEGIN_ALLOW_THREADS/ 89 Py_END_ALLOW_THREADS macros are acceptable. 90 91 The return value is an opaque "handle" to the thread state when 92 PyGILState_Ensure() was called, and must be passed to 93 PyGILState_Release() to ensure Python is left in the same state. Even 94 though recursive calls are allowed, these handles can *not* be shared - 95 each unique call to PyGILState_Ensure must save the handle for its 96 call to PyGILState_Release. 97 98 When the function returns, the current thread will hold the GIL. 99 100 Failure is a fatal error. 101 */ 102 PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void); 103 104 /* Release any resources previously acquired. After this call, Python's 105 state will be the same as it was prior to the corresponding 106 PyGILState_Ensure() call (but generally this state will be unknown to 107 the caller, hence the use of the GILState API.) 108 109 Every call to PyGILState_Ensure must be matched by a call to 110 PyGILState_Release on the same thread. 111 */ 112 PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE); 113 114 /* Helper/diagnostic function - get the current thread state for 115 this thread. May return NULL if no GILState API has been used 116 on the current thread. Note that the main thread always has such a 117 thread-state, even if no auto-thread-state call has been made 118 on the main thread. 119 */ 120 PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void); 121 122 123 #ifndef Py_LIMITED_API 124 # define Py_CPYTHON_PYSTATE_H 125 # include "cpython/pystate.h" 126 # undef Py_CPYTHON_PYSTATE_H 127 #endif 128 129 #ifdef __cplusplus 130 } 131 #endif 132 #endif /* !Py_PYSTATE_H */ 133