blob: 42391085f9148652034c6239b0ae80d504ffca28 [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
Guido van Rossuma027efa1997-05-05 20:56:21 +000032
33} PyInterpreterState;
34
35
36/* State unique per thread */
37
38struct _frame; /* Avoid including frameobject.h */
39
Fred Drake55fb6e02001-06-27 19:18:03 +000040/* Py_tracefunc return -1 when raising an exception, or 0 for success. */
41typedef int (*Py_tracefunc)(PyObject *, struct _frame *, int, PyObject *);
42
43/* The following values are used for 'what' for tracefunc functions: */
44#define PyTrace_CALL 0
45#define PyTrace_EXCEPTION 1
46#define PyTrace_LINE 2
47#define PyTrace_RETURN 3
Nicholas Bastinc69ebe82004-03-24 21:57:10 +000048#define PyTrace_C_CALL 4
49#define PyTrace_C_EXCEPTION 5
50#define PyTrace_C_RETURN 6
Fred Drake55fb6e02001-06-27 19:18:03 +000051
Guido van Rossuma027efa1997-05-05 20:56:21 +000052typedef struct _ts {
53
Fred Drake5eb6d4e2000-07-08 23:37:28 +000054 struct _ts *next;
55 PyInterpreterState *interp;
Guido van Rossuma027efa1997-05-05 20:56:21 +000056
Fred Drake5eb6d4e2000-07-08 23:37:28 +000057 struct _frame *frame;
58 int recursion_depth;
Fred Drake5eb6d4e2000-07-08 23:37:28 +000059 int tracing;
Fred Drake9e3ad782001-07-03 23:39:52 +000060 int use_tracing;
Guido van Rossuma027efa1997-05-05 20:56:21 +000061
Fred Drake55fb6e02001-06-27 19:18:03 +000062 Py_tracefunc c_profilefunc;
63 Py_tracefunc c_tracefunc;
64 PyObject *c_profileobj;
65 PyObject *c_traceobj;
Guido van Rossuma027efa1997-05-05 20:56:21 +000066
Fred Drake5eb6d4e2000-07-08 23:37:28 +000067 PyObject *curexc_type;
68 PyObject *curexc_value;
69 PyObject *curexc_traceback;
Guido van Rossuma027efa1997-05-05 20:56:21 +000070
Fred Drake5eb6d4e2000-07-08 23:37:28 +000071 PyObject *exc_type;
72 PyObject *exc_value;
73 PyObject *exc_traceback;
Guido van Rossuma027efa1997-05-05 20:56:21 +000074
Fred Drake5eb6d4e2000-07-08 23:37:28 +000075 PyObject *dict;
Guido van Rossumee0a63b1998-04-13 20:24:05 +000076
Tim Peters174175b2004-03-29 02:24:26 +000077 /* tick_counter is incremented whenever the check_interval ticker
78 * reaches zero. The purpose is to give a useful measure of the number
79 * of interpreted bytecode instructions in a given thread. This
80 * extremely lightweight statistic collector may be of interest to
81 * profilers (like psyco.jit()), although nothing in the core uses it.
82 */
Michael W. Hudson019a78e2002-11-08 12:53:11 +000083 int tick_counter;
Tim Peters174175b2004-03-29 02:24:26 +000084
Mark Hammond8d98d2c2003-04-19 15:41:53 +000085 int gilstate_counter;
Michael W. Hudson019a78e2002-11-08 12:53:11 +000086
Guido van Rossumb8b6d0c2003-06-28 21:53:52 +000087 PyObject *async_exc; /* Asynchronous exception to raise */
88 long thread_id; /* Thread id where this tstate was created */
89
Fred Drake5eb6d4e2000-07-08 23:37:28 +000090 /* XXX signal handlers should also be here */
Guido van Rossuma027efa1997-05-05 20:56:21 +000091
92} PyThreadState;
93
94
Mark Hammond91a681d2002-08-12 07:21:58 +000095PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void);
96PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *);
97PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *);
Guido van Rossuma027efa1997-05-05 20:56:21 +000098
Mark Hammond91a681d2002-08-12 07:21:58 +000099PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *);
100PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *);
101PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *);
Guido van Rossum29757862001-01-23 01:46:06 +0000102#ifdef WITH_THREAD
Mark Hammond91a681d2002-08-12 07:21:58 +0000103PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
Guido van Rossum29757862001-01-23 01:46:06 +0000104#endif
Guido van Rossuma027efa1997-05-05 20:56:21 +0000105
Mark Hammond91a681d2002-08-12 07:21:58 +0000106PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void);
107PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *);
108PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void);
Guido van Rossumb8b6d0c2003-06-28 21:53:52 +0000109PyAPI_FUNC(int) PyThreadState_SetAsyncExc(long, PyObject *);
Guido van Rossuma027efa1997-05-05 20:56:21 +0000110
Guido van Rossum275ea671998-12-21 18:28:10 +0000111
112/* Variable and macro for in-line access to current thread state */
113
Mark Hammond91a681d2002-08-12 07:21:58 +0000114PyAPI_DATA(PyThreadState *) _PyThreadState_Current;
Guido van Rossum275ea671998-12-21 18:28:10 +0000115
116#ifdef Py_DEBUG
117#define PyThreadState_GET() PyThreadState_Get()
118#else
119#define PyThreadState_GET() (_PyThreadState_Current)
120#endif
121
Tim Peters174175b2004-03-29 02:24:26 +0000122typedef
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000123 enum {PyGILState_LOCKED, PyGILState_UNLOCKED}
124 PyGILState_STATE;
125
126/* Ensure that the current thread is ready to call the Python
127 C API, regardless of the current state of Python, or of its
128 thread lock. This may be called as many times as desired
Tim Peters174175b2004-03-29 02:24:26 +0000129 by a thread so long as each call is matched with a call to
130 PyGILState_Release(). In general, other thread-state APIs may
131 be used between _Ensure() and _Release() calls, so long as the
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000132 thread-state is restored to its previous state before the Release().
133 For example, normal use of the Py_BEGIN_ALLOW_THREADS/
134 Py_END_ALLOW_THREADS macros are acceptable.
135
136 The return value is an opaque "handle" to the thread state when
Raymond Hettinger4eec95a2004-03-13 20:45:47 +0000137 PyGILState_Ensure() was called, and must be passed to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000138 PyGILState_Release() to ensure Python is left in the same state. Even
Tim Peters174175b2004-03-29 02:24:26 +0000139 though recursive calls are allowed, these handles can *not* be shared -
140 each unique call to PyGILState_Ensure must save the handle for its
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000141 call to PyGILState_Release.
142
143 When the function returns, the current thread will hold the GIL.
144
145 Failure is a fatal error.
146*/
147PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void);
148
149/* Release any resources previously acquired. After this call, Python's
150 state will be the same as it was prior to the corresponding
Tim Peters174175b2004-03-29 02:24:26 +0000151 PyGILState_Ensure() call (but generally this state will be unknown to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000152 the caller, hence the use of the GILState API.)
153
Tim Peters174175b2004-03-29 02:24:26 +0000154 Every call to PyGILState_Ensure must be matched by a call to
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000155 PyGILState_Release on the same thread.
156*/
157PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE);
158
159/* Helper/diagnostic function - get the current thread state for
Tim Peters174175b2004-03-29 02:24:26 +0000160 this thread. May return NULL if no GILState API has been used
161 on the current thread. Note the main thread always has such a
162 thread-state, even if no auto-thread-state call has been made
Mark Hammond8d98d2c2003-04-19 15:41:53 +0000163 on the main thread.
164*/
165PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void);
166
Guido van Rossumf5df46d2001-07-19 12:19:27 +0000167/* Routines for advanced debuggers, requested by David Beazley.
168 Don't use unless you know what you are doing! */
Mark Hammond91a681d2002-08-12 07:21:58 +0000169PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
170PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
171PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
172PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
Guido van Rossumf5df46d2001-07-19 12:19:27 +0000173
Guido van Rossum6297a7a2003-02-19 15:53:17 +0000174typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_);
175
Michael W. Hudson019a78e2002-11-08 12:53:11 +0000176/* hook for PyEval_GetFrame(), requested for Psyco */
Guido van Rossum6297a7a2003-02-19 15:53:17 +0000177PyAPI_DATA(PyThreadFrameGetter) _PyThreadState_GetFrame;
Michael W. Hudson019a78e2002-11-08 12:53:11 +0000178
Guido van Rossuma027efa1997-05-05 20:56:21 +0000179#ifdef __cplusplus
180}
181#endif
182#endif /* !Py_PYSTATE_H */