blob: cf2969596310499f617c0a6abea1d69063635782 [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;
22 PyObject *sysdict;
23 PyObject *builtins;
Guido van Rossuma027efa1997-05-05 20:56:21 +000024
Gustavo Niemeyer5ddd4c32003-03-19 00:35:36 +000025 PyObject *codec_search_path;
26 PyObject *codec_search_cache;
27 PyObject *codec_error_registry;
28
Martin v. Löwisf0473d52001-07-18 16:17:16 +000029#ifdef HAVE_DLOPEN
30 int dlopenflags;
31#endif
Martin v. Löwisf30d60e2004-06-08 08:17:44 +000032#ifdef WITH_TSC
33 int tscdump;
34#endif
Guido van Rossuma027efa1997-05-05 20:56:21 +000035
36} PyInterpreterState;
37
38
39/* State unique per thread */
40
41struct _frame; /* Avoid including frameobject.h */
42
Fred Drake55fb6e02001-06-27 19:18:03 +000043/* Py_tracefunc return -1 when raising an exception, or 0 for success. */
44typedef int (*Py_tracefunc)(PyObject *, struct _frame *, int, PyObject *);
45
46/* The following values are used for 'what' for tracefunc functions: */
47#define PyTrace_CALL 0
48#define PyTrace_EXCEPTION 1
49#define PyTrace_LINE 2
50#define PyTrace_RETURN 3
Nicholas Bastinc69ebe82004-03-24 21:57:10 +000051#define PyTrace_C_CALL 4
52#define PyTrace_C_EXCEPTION 5
53#define PyTrace_C_RETURN 6
Fred Drake55fb6e02001-06-27 19:18:03 +000054
Guido van Rossuma027efa1997-05-05 20:56:21 +000055typedef struct _ts {
Brett Cannon55fa66d2005-06-25 07:07:35 +000056 /* See Python/ceval.c for comments explaining most fields */
Guido van Rossuma027efa1997-05-05 20:56:21 +000057
Fred Drake5eb6d4e2000-07-08 23:37:28 +000058 struct _ts *next;
59 PyInterpreterState *interp;
Guido van Rossuma027efa1997-05-05 20:56:21 +000060
Fred Drake5eb6d4e2000-07-08 23:37:28 +000061 struct _frame *frame;
62 int recursion_depth;
Brett Cannon55fa66d2005-06-25 07:07:35 +000063 /* 'tracing' keeps track of the execution depth when tracing/profiling.
64 This is to prevent the actual trace/profile code from being recorded in
65 the trace/profile. */
Fred Drake5eb6d4e2000-07-08 23:37:28 +000066 int tracing;
Fred Drake9e3ad782001-07-03 23:39:52 +000067 int use_tracing;
Guido van Rossuma027efa1997-05-05 20:56:21 +000068
Fred Drake55fb6e02001-06-27 19:18:03 +000069 Py_tracefunc c_profilefunc;
70 Py_tracefunc c_tracefunc;
71 PyObject *c_profileobj;
72 PyObject *c_traceobj;
Guido van Rossuma027efa1997-05-05 20:56:21 +000073
Fred Drake5eb6d4e2000-07-08 23:37:28 +000074 PyObject *curexc_type;
75 PyObject *curexc_value;
76 PyObject *curexc_traceback;
Guido van Rossuma027efa1997-05-05 20:56:21 +000077
Fred Drake5eb6d4e2000-07-08 23:37:28 +000078 PyObject *exc_type;
79 PyObject *exc_value;
80 PyObject *exc_traceback;
Guido van Rossuma027efa1997-05-05 20:56:21 +000081
Brett Cannon55fa66d2005-06-25 07:07:35 +000082 PyObject *dict; /* Stores per-thread state */
Guido van Rossumee0a63b1998-04-13 20:24:05 +000083
Tim Peters174175b2004-03-29 02:24:26 +000084 /* tick_counter is incremented whenever the check_interval ticker
85 * reaches zero. The purpose is to give a useful measure of the number
86 * of interpreted bytecode instructions in a given thread. This
87 * extremely lightweight statistic collector may be of interest to
88 * profilers (like psyco.jit()), although nothing in the core uses it.
89 */
Michael W. Hudson019a78e2002-11-08 12:53:11 +000090 int tick_counter;
Tim Peters174175b2004-03-29 02:24:26 +000091
Mark Hammond8d98d2c2003-04-19 15:41:53 +000092 int gilstate_counter;
Michael W. Hudson019a78e2002-11-08 12:53:11 +000093
Guido van Rossumb8b6d0c2003-06-28 21:53:52 +000094 PyObject *async_exc; /* Asynchronous exception to raise */
95 long thread_id; /* Thread id where this tstate was created */
96
Fred Drake5eb6d4e2000-07-08 23:37:28 +000097 /* XXX signal handlers should also be here */
Guido van Rossuma027efa1997-05-05 20:56:21 +000098
99} PyThreadState;
100
101
Mark Hammond91a681d2002-08-12 07:21:58 +0000102PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void);
103PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *);
104PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *);
Guido van Rossuma027efa1997-05-05 20:56:21 +0000105
Mark Hammond91a681d2002-08-12 07:21:58 +0000106PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *);
107PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *);
108PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *);
Guido van Rossum29757862001-01-23 01:46:06 +0000109#ifdef WITH_THREAD
Mark Hammond91a681d2002-08-12 07:21:58 +0000110PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
Guido van Rossum29757862001-01-23 01:46:06 +0000111#endif
Guido van Rossuma027efa1997-05-05 20:56:21 +0000112
Mark Hammond91a681d2002-08-12 07:21:58 +0000113PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void);
114PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *);
115PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void);
Guido van Rossumb8b6d0c2003-06-28 21:53:52 +0000116PyAPI_FUNC(int) PyThreadState_SetAsyncExc(long, PyObject *);
Guido van Rossuma027efa1997-05-05 20:56:21 +0000117
Guido van Rossum275ea671998-12-21 18:28:10 +0000118
119/* Variable and macro for in-line access to current thread state */
120
Mark Hammond91a681d2002-08-12 07:21:58 +0000121PyAPI_DATA(PyThreadState *) _PyThreadState_Current;
Guido van Rossum275ea671998-12-21 18:28:10 +0000122
123#ifdef Py_DEBUG
124#define PyThreadState_GET() PyThreadState_Get()
125#else
126#define PyThreadState_GET() (_PyThreadState_Current)
127#endif
128
Tim Peters174175b2004-03-29 02:24:26 +0000129typedef
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000130 enum {PyGILState_LOCKED, PyGILState_UNLOCKED}
131 PyGILState_STATE;
132
133/* Ensure that the current thread is ready to call the Python
134 C API, regardless of the current state of Python, or of its
135 thread lock. This may be called as many times as desired
Tim Peters174175b2004-03-29 02:24:26 +0000136 by a thread so long as each call is matched with a call to
137 PyGILState_Release(). In general, other thread-state APIs may
138 be used between _Ensure() and _Release() calls, so long as the
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000139 thread-state is restored to its previous state before the Release().
140 For example, normal use of the Py_BEGIN_ALLOW_THREADS/
141 Py_END_ALLOW_THREADS macros are acceptable.
142
143 The return value is an opaque "handle" to the thread state when
Raymond Hettinger4eec95a2004-03-13 20:45:47 +0000144 PyGILState_Ensure() was called, and must be passed to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000145 PyGILState_Release() to ensure Python is left in the same state. Even
Tim Peters174175b2004-03-29 02:24:26 +0000146 though recursive calls are allowed, these handles can *not* be shared -
147 each unique call to PyGILState_Ensure must save the handle for its
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000148 call to PyGILState_Release.
149
150 When the function returns, the current thread will hold the GIL.
151
152 Failure is a fatal error.
153*/
154PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void);
155
156/* Release any resources previously acquired. After this call, Python's
157 state will be the same as it was prior to the corresponding
Tim Peters174175b2004-03-29 02:24:26 +0000158 PyGILState_Ensure() call (but generally this state will be unknown to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000159 the caller, hence the use of the GILState API.)
160
Tim Peters174175b2004-03-29 02:24:26 +0000161 Every call to PyGILState_Ensure must be matched by a call to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000162 PyGILState_Release on the same thread.
163*/
164PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE);
165
166/* Helper/diagnostic function - get the current thread state for
Tim Peters174175b2004-03-29 02:24:26 +0000167 this thread. May return NULL if no GILState API has been used
168 on the current thread. Note the main thread always has such a
169 thread-state, even if no auto-thread-state call has been made
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000170 on the main thread.
171*/
172PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void);
173
Tim Peters32a83612006-07-10 21:08:24 +0000174/* The implementation of sys._current_frames() Returns a dict mapping
175 thread id to that thread's current frame.
176*/
177PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void);
178
Guido van Rossumf5df46d2001-07-19 12:19:27 +0000179/* Routines for advanced debuggers, requested by David Beazley.
180 Don't use unless you know what you are doing! */
Mark Hammond91a681d2002-08-12 07:21:58 +0000181PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
182PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
183PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
184PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
Guido van Rossumf5df46d2001-07-19 12:19:27 +0000185
Guido van Rossum6297a7a2003-02-19 15:53:17 +0000186typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_);
187
Michael W. Hudson019a78e2002-11-08 12:53:11 +0000188/* hook for PyEval_GetFrame(), requested for Psyco */
Guido van Rossum6297a7a2003-02-19 15:53:17 +0000189PyAPI_DATA(PyThreadFrameGetter) _PyThreadState_GetFrame;
Michael W. Hudson019a78e2002-11-08 12:53:11 +0000190
Guido van Rossuma027efa1997-05-05 20:56:21 +0000191#ifdef __cplusplus
192}
193#endif
194#endif /* !Py_PYSTATE_H */