blob: c27e82735ac8b522b1a9d5609362e581f93c25ce [file] [log] [blame]
Guido van Rossuma027efa1997-05-05 20:56:21 +00001
2/* Thread and interpreter state structures and their interfaces */
3
4
Fred Drake5eb6d4e2000-07-08 23:37:28 +00005#ifndef Py_PYSTATE_H
6#define Py_PYSTATE_H
7#ifdef __cplusplus
8extern "C" {
9#endif
10
Guido van Rossuma027efa1997-05-05 20:56:21 +000011/* State shared between threads */
12
Guido van Rossum29e46a91997-08-02 02:56:48 +000013struct _ts; /* Forward */
14struct _is; /* Forward */
15
Guido van Rossuma027efa1997-05-05 20:56:21 +000016typedef struct _is {
17
Fred Drake5eb6d4e2000-07-08 23:37:28 +000018 struct _is *next;
19 struct _ts *tstate_head;
Guido van Rossum29e46a91997-08-02 02:56:48 +000020
Fred Drake5eb6d4e2000-07-08 23:37:28 +000021 PyObject *modules;
Martin v. Löwis1a214512008-06-11 05:26:20 +000022 PyObject *modules_by_index;
Fred Drake5eb6d4e2000-07-08 23:37:28 +000023 PyObject *sysdict;
24 PyObject *builtins;
Guido van Rossumd8faa362007-04-27 19:54:29 +000025 PyObject *modules_reloading;
Guido van Rossuma027efa1997-05-05 20:56:21 +000026
Gustavo Niemeyer5ddd4c32003-03-19 00:35:36 +000027 PyObject *codec_search_path;
28 PyObject *codec_search_cache;
29 PyObject *codec_error_registry;
Christian Heimes6a27efa2008-10-30 21:48:26 +000030 int codecs_initialized;
Gustavo Niemeyer5ddd4c32003-03-19 00:35:36 +000031
Martin v. Löwisf0473d52001-07-18 16:17:16 +000032#ifdef HAVE_DLOPEN
33 int dlopenflags;
34#endif
Martin v. Löwisf30d60e2004-06-08 08:17:44 +000035#ifdef WITH_TSC
36 int tscdump;
37#endif
Guido van Rossuma027efa1997-05-05 20:56:21 +000038
39} PyInterpreterState;
40
41
42/* State unique per thread */
43
44struct _frame; /* Avoid including frameobject.h */
45
Fred Drake55fb6e02001-06-27 19:18:03 +000046/* Py_tracefunc return -1 when raising an exception, or 0 for success. */
47typedef int (*Py_tracefunc)(PyObject *, struct _frame *, int, PyObject *);
48
49/* The following values are used for 'what' for tracefunc functions: */
50#define PyTrace_CALL 0
51#define PyTrace_EXCEPTION 1
52#define PyTrace_LINE 2
53#define PyTrace_RETURN 3
Nicholas Bastinc69ebe82004-03-24 21:57:10 +000054#define PyTrace_C_CALL 4
55#define PyTrace_C_EXCEPTION 5
56#define PyTrace_C_RETURN 6
Fred Drake55fb6e02001-06-27 19:18:03 +000057
Guido van Rossuma027efa1997-05-05 20:56:21 +000058typedef struct _ts {
Brett Cannon55fa66d2005-06-25 07:07:35 +000059 /* See Python/ceval.c for comments explaining most fields */
Guido van Rossuma027efa1997-05-05 20:56:21 +000060
Fred Drake5eb6d4e2000-07-08 23:37:28 +000061 struct _ts *next;
62 PyInterpreterState *interp;
Guido van Rossuma027efa1997-05-05 20:56:21 +000063
Fred Drake5eb6d4e2000-07-08 23:37:28 +000064 struct _frame *frame;
65 int recursion_depth;
Martin v. Löwis5b222132007-06-10 09:51:05 +000066 char overflowed; /* The stack has overflowed. Allow 50 more calls
67 to handle the runtime error. */
68 char recursion_critical; /* The current calls must not cause
69 a stack overflow. */
Brett Cannon55fa66d2005-06-25 07:07:35 +000070 /* 'tracing' keeps track of the execution depth when tracing/profiling.
71 This is to prevent the actual trace/profile code from being recorded in
72 the trace/profile. */
Fred Drake5eb6d4e2000-07-08 23:37:28 +000073 int tracing;
Fred Drake9e3ad782001-07-03 23:39:52 +000074 int use_tracing;
Guido van Rossuma027efa1997-05-05 20:56:21 +000075
Fred Drake55fb6e02001-06-27 19:18:03 +000076 Py_tracefunc c_profilefunc;
77 Py_tracefunc c_tracefunc;
78 PyObject *c_profileobj;
79 PyObject *c_traceobj;
Guido van Rossuma027efa1997-05-05 20:56:21 +000080
Fred Drake5eb6d4e2000-07-08 23:37:28 +000081 PyObject *curexc_type;
82 PyObject *curexc_value;
83 PyObject *curexc_traceback;
Guido van Rossuma027efa1997-05-05 20:56:21 +000084
Fred Drake5eb6d4e2000-07-08 23:37:28 +000085 PyObject *exc_type;
86 PyObject *exc_value;
87 PyObject *exc_traceback;
Guido van Rossuma027efa1997-05-05 20:56:21 +000088
Brett Cannon55fa66d2005-06-25 07:07:35 +000089 PyObject *dict; /* Stores per-thread state */
Guido van Rossumee0a63b1998-04-13 20:24:05 +000090
Antoine Pitrou074e5ed2009-11-10 19:50:40 +000091 /* XXX doesn't mean anything anymore (the comment below is obsolete)
92 => deprecate or remove? */
Tim Peters174175b2004-03-29 02:24:26 +000093 /* tick_counter is incremented whenever the check_interval ticker
94 * reaches zero. The purpose is to give a useful measure of the number
95 * of interpreted bytecode instructions in a given thread. This
96 * extremely lightweight statistic collector may be of interest to
97 * profilers (like psyco.jit()), although nothing in the core uses it.
98 */
Michael W. Hudson019a78e2002-11-08 12:53:11 +000099 int tick_counter;
Tim Peters174175b2004-03-29 02:24:26 +0000100
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000101 int gilstate_counter;
Michael W. Hudson019a78e2002-11-08 12:53:11 +0000102
Guido van Rossumb8b6d0c2003-06-28 21:53:52 +0000103 PyObject *async_exc; /* Asynchronous exception to raise */
104 long thread_id; /* Thread id where this tstate was created */
105
Fred Drake5eb6d4e2000-07-08 23:37:28 +0000106 /* XXX signal handlers should also be here */
Guido van Rossuma027efa1997-05-05 20:56:21 +0000107
108} PyThreadState;
109
110
Mark Hammond91a681d2002-08-12 07:21:58 +0000111PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void);
112PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *);
113PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *);
Martin v. Löwis1a214512008-06-11 05:26:20 +0000114PyAPI_FUNC(int) _PyState_AddModule(PyObject*, struct PyModuleDef*);
115PyAPI_FUNC(PyObject*) PyState_FindModule(struct PyModuleDef*);
Guido van Rossuma027efa1997-05-05 20:56:21 +0000116
Mark Hammond91a681d2002-08-12 07:21:58 +0000117PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *);
118PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *);
119PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *);
Guido van Rossum29757862001-01-23 01:46:06 +0000120#ifdef WITH_THREAD
Mark Hammond91a681d2002-08-12 07:21:58 +0000121PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
Guido van Rossum29757862001-01-23 01:46:06 +0000122#endif
Guido van Rossuma027efa1997-05-05 20:56:21 +0000123
Mark Hammond91a681d2002-08-12 07:21:58 +0000124PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void);
125PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *);
126PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void);
Guido van Rossumb8b6d0c2003-06-28 21:53:52 +0000127PyAPI_FUNC(int) PyThreadState_SetAsyncExc(long, PyObject *);
Guido van Rossuma027efa1997-05-05 20:56:21 +0000128
Guido van Rossum275ea671998-12-21 18:28:10 +0000129
130/* Variable and macro for in-line access to current thread state */
131
Mark Hammond91a681d2002-08-12 07:21:58 +0000132PyAPI_DATA(PyThreadState *) _PyThreadState_Current;
Guido van Rossum275ea671998-12-21 18:28:10 +0000133
134#ifdef Py_DEBUG
135#define PyThreadState_GET() PyThreadState_Get()
136#else
137#define PyThreadState_GET() (_PyThreadState_Current)
138#endif
139
Tim Peters174175b2004-03-29 02:24:26 +0000140typedef
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000141 enum {PyGILState_LOCKED, PyGILState_UNLOCKED}
142 PyGILState_STATE;
143
144/* Ensure that the current thread is ready to call the Python
145 C API, regardless of the current state of Python, or of its
146 thread lock. This may be called as many times as desired
Tim Peters174175b2004-03-29 02:24:26 +0000147 by a thread so long as each call is matched with a call to
148 PyGILState_Release(). In general, other thread-state APIs may
149 be used between _Ensure() and _Release() calls, so long as the
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000150 thread-state is restored to its previous state before the Release().
151 For example, normal use of the Py_BEGIN_ALLOW_THREADS/
152 Py_END_ALLOW_THREADS macros are acceptable.
153
154 The return value is an opaque "handle" to the thread state when
Raymond Hettinger4eec95a2004-03-13 20:45:47 +0000155 PyGILState_Ensure() was called, and must be passed to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000156 PyGILState_Release() to ensure Python is left in the same state. Even
Tim Peters174175b2004-03-29 02:24:26 +0000157 though recursive calls are allowed, these handles can *not* be shared -
158 each unique call to PyGILState_Ensure must save the handle for its
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000159 call to PyGILState_Release.
160
161 When the function returns, the current thread will hold the GIL.
162
163 Failure is a fatal error.
164*/
165PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void);
166
167/* Release any resources previously acquired. After this call, Python's
168 state will be the same as it was prior to the corresponding
Tim Peters174175b2004-03-29 02:24:26 +0000169 PyGILState_Ensure() call (but generally this state will be unknown to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000170 the caller, hence the use of the GILState API.)
171
Tim Peters174175b2004-03-29 02:24:26 +0000172 Every call to PyGILState_Ensure must be matched by a call to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000173 PyGILState_Release on the same thread.
174*/
175PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE);
176
177/* Helper/diagnostic function - get the current thread state for
Tim Peters174175b2004-03-29 02:24:26 +0000178 this thread. May return NULL if no GILState API has been used
179 on the current thread. Note the main thread always has such a
180 thread-state, even if no auto-thread-state call has been made
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000181 on the main thread.
182*/
183PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void);
184
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000185/* The implementation of sys._current_frames() Returns a dict mapping
186 thread id to that thread's current frame.
187*/
188PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void);
189
Guido van Rossumf5df46d2001-07-19 12:19:27 +0000190/* Routines for advanced debuggers, requested by David Beazley.
191 Don't use unless you know what you are doing! */
Mark Hammond91a681d2002-08-12 07:21:58 +0000192PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
193PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
194PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
195PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
Guido van Rossumf5df46d2001-07-19 12:19:27 +0000196
Guido van Rossum6297a7a2003-02-19 15:53:17 +0000197typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_);
198
Michael W. Hudson019a78e2002-11-08 12:53:11 +0000199/* hook for PyEval_GetFrame(), requested for Psyco */
Guido van Rossum6297a7a2003-02-19 15:53:17 +0000200PyAPI_DATA(PyThreadFrameGetter) _PyThreadState_GetFrame;
Michael W. Hudson019a78e2002-11-08 12:53:11 +0000201
Guido van Rossuma027efa1997-05-05 20:56:21 +0000202#ifdef __cplusplus
203}
204#endif
205#endif /* !Py_PYSTATE_H */