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 */