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
8extern "C" {
9#endif
10
11/* State shared between threads */
12
13struct _ts; /* Forward */
14struct _is; /* Forward */
15
16#ifdef Py_LIMITED_API
17typedef struct _is PyInterpreterState;
18#else
19typedef 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
50struct _frame; /* Avoid including frameobject.h */
51
52#ifndef Py_LIMITED_API
53/* Py_tracefunc return -1 when raising an exception, or 0 for success. */
54typedef 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
67typedef struct _ts PyThreadState;
68#else
69typedef 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
146PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void);
147PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *);
148PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *);
149PyAPI_FUNC(int) _PyState_AddModule(PyObject*, struct PyModuleDef*);
150#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
151/* New in 3.3 */
152PyAPI_FUNC(int) PyState_AddModule(PyObject*, struct PyModuleDef*);
153PyAPI_FUNC(int) PyState_RemoveModule(struct PyModuleDef*);
154#endif
155PyAPI_FUNC(PyObject*) PyState_FindModule(struct PyModuleDef*);
156#ifndef Py_LIMITED_API
157PyAPI_FUNC(void) _PyState_ClearModules(void);
158#endif
159
160PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *);
161PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *);
162PyAPI_FUNC(void) _PyThreadState_Init(PyThreadState *);
163PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *);
164PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *);
165PyAPI_FUNC(void) _PyThreadState_DeleteExcept(PyThreadState *tstate);
166#ifdef WITH_THREAD
167PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
168PyAPI_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). */
174PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void);
175
176/* Similar to PyThreadState_Get(), but don't issue a fatal error
177 * if it is NULL. */
178PyAPI_FUNC(PyThreadState *) _PyThreadState_UncheckedGet(void);
179
180PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *);
181PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void);
182PyAPI_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
190PyAPI_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
197typedef
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*/
224PyAPI_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*/
234PyAPI_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*/
242PyAPI_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
248PyAPI_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
257PyAPI_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
263PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
264PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
265PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
266PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
267
268typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_);
269#endif
270
271/* hook for PyEval_GetFrame(), requested for Psyco */
272#ifndef Py_LIMITED_API
273PyAPI_DATA(PyThreadFrameGetter) _PyThreadState_GetFrame;
274#endif
275
276#ifdef __cplusplus
277}
278#endif
279#endif /* !Py_PYSTATE_H */
280