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