pystate.h 7.31 KB
Newer Older
1 2 3 4

/* Thread and interpreter state structures and their interfaces */


5 6 7 8 9 10
#ifndef Py_PYSTATE_H
#define Py_PYSTATE_H
#ifdef __cplusplus
extern "C" {
#endif

11 12
/* State shared between threads */

13 14 15
struct _ts; /* Forward */
struct _is; /* Forward */

16 17 18
#ifdef Py_LIMITED_API
typedef struct _is PyInterpreterState;
#else
19 20
typedef struct _is {

21 22
    struct _is *next;
    struct _ts *tstate_head;
23

24
    PyObject *modules;
25
    PyObject *modules_by_index;
26 27
    PyObject *sysdict;
    PyObject *builtins;
28
    PyObject *modules_reloading;
29

30 31 32
    PyObject *codec_search_path;
    PyObject *codec_search_cache;
    PyObject *codec_error_registry;
33
    int codecs_initialized;
34
    int fscodec_initialized;
35

36 37 38
#ifdef HAVE_DLOPEN
    int dlopenflags;
#endif
39 40 41
#ifdef WITH_TSC
    int tscdump;
#endif
42 43

} PyInterpreterState;
44
#endif
45 46 47 48 49 50


/* State unique per thread */

struct _frame; /* Avoid including frameobject.h */

51
#ifndef Py_LIMITED_API
52 53 54 55 56 57 58 59
/* Py_tracefunc return -1 when raising an exception, or 0 for success. */
typedef int (*Py_tracefunc)(PyObject *, struct _frame *, int, PyObject *);

/* The following values are used for 'what' for tracefunc functions: */
#define PyTrace_CALL 0
#define PyTrace_EXCEPTION 1
#define PyTrace_LINE 2
#define PyTrace_RETURN 3
60 61 62
#define PyTrace_C_CALL 4
#define PyTrace_C_EXCEPTION 5
#define PyTrace_C_RETURN 6
63
#endif
64

65 66 67
#ifdef Py_LIMITED_API
typedef struct _ts PyThreadState;
#else
68
typedef struct _ts {
69
    /* See Python/ceval.c for comments explaining most fields */
70

71 72
    struct _ts *next;
    PyInterpreterState *interp;
73

74 75
    struct _frame *frame;
    int recursion_depth;
76
    char overflowed; /* The stack has overflowed. Allow 50 more calls
77 78 79
                        to handle the runtime error. */
    char recursion_critical; /* The current calls must not cause
                                a stack overflow. */
80 81 82
    /* 'tracing' keeps track of the execution depth when tracing/profiling.
       This is to prevent the actual trace/profile code from being recorded in
       the trace/profile. */
83
    int tracing;
84
    int use_tracing;
85

86 87 88 89
    Py_tracefunc c_profilefunc;
    Py_tracefunc c_tracefunc;
    PyObject *c_profileobj;
    PyObject *c_traceobj;
90

91 92 93
    PyObject *curexc_type;
    PyObject *curexc_value;
    PyObject *curexc_traceback;
94

95 96 97
    PyObject *exc_type;
    PyObject *exc_value;
    PyObject *exc_traceback;
98

99
    PyObject *dict;  /* Stores per-thread state */
100

Antoine Pitrou's avatar
Antoine Pitrou committed
101 102
    /* XXX doesn't mean anything anymore (the comment below is obsolete)
       => deprecate or remove? */
103 104 105 106 107 108
    /* tick_counter is incremented whenever the check_interval ticker
     * reaches zero. The purpose is to give a useful measure of the number
     * of interpreted bytecode instructions in a given thread.  This
     * extremely lightweight statistic collector may be of interest to
     * profilers (like psyco.jit()), although nothing in the core uses it.
     */
109
    int tick_counter;
110

111
    int gilstate_counter;
112

113 114 115
    PyObject *async_exc; /* Asynchronous exception to raise */
    long thread_id; /* Thread id where this tstate was created */

116
    /* XXX signal handlers should also be here */
117 118

} PyThreadState;
119
#endif
120 121


122 123 124
PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_New(void);
PyAPI_FUNC(void) PyInterpreterState_Clear(PyInterpreterState *);
PyAPI_FUNC(void) PyInterpreterState_Delete(PyInterpreterState *);
125 126
PyAPI_FUNC(int) _PyState_AddModule(PyObject*, struct PyModuleDef*);
PyAPI_FUNC(PyObject*) PyState_FindModule(struct PyModuleDef*);
127

128
PyAPI_FUNC(PyThreadState *) PyThreadState_New(PyInterpreterState *);
129 130
PyAPI_FUNC(PyThreadState *) _PyThreadState_Prealloc(PyInterpreterState *);
PyAPI_FUNC(void) _PyThreadState_Init(PyThreadState *);
131 132
PyAPI_FUNC(void) PyThreadState_Clear(PyThreadState *);
PyAPI_FUNC(void) PyThreadState_Delete(PyThreadState *);
133
#ifdef WITH_THREAD
134
PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
135
PyAPI_FUNC(void) _PyGILState_Reinit(void);
136
#endif
137

138 139 140
PyAPI_FUNC(PyThreadState *) PyThreadState_Get(void);
PyAPI_FUNC(PyThreadState *) PyThreadState_Swap(PyThreadState *);
PyAPI_FUNC(PyObject *) PyThreadState_GetDict(void);
141
PyAPI_FUNC(int) PyThreadState_SetAsyncExc(long, PyObject *);
142

143 144 145

/* Variable and macro for in-line access to current thread state */

146 147
/* Assuming the current thread holds the GIL, this is the
   PyThreadState for the current thread. */
148
#ifndef Py_LIMITED_API
149
PyAPI_DATA(_Py_atomic_address) _PyThreadState_Current;
150
#endif
151

152
#if defined(Py_DEBUG) || defined(Py_LIMITED_API)
153 154
#define PyThreadState_GET() PyThreadState_Get()
#else
155 156
#define PyThreadState_GET() \
    ((PyThreadState*)_Py_atomic_load_relaxed(&_PyThreadState_Current))
157 158
#endif

159
typedef
160 161 162
    enum {PyGILState_LOCKED, PyGILState_UNLOCKED}
        PyGILState_STATE;

163 164
#ifdef WITH_THREAD

165 166 167
/* Ensure that the current thread is ready to call the Python
   C API, regardless of the current state of Python, or of its
   thread lock.  This may be called as many times as desired
168 169 170
   by a thread so long as each call is matched with a call to
   PyGILState_Release().  In general, other thread-state APIs may
   be used between _Ensure() and _Release() calls, so long as the
171 172 173 174 175
   thread-state is restored to its previous state before the Release().
   For example, normal use of the Py_BEGIN_ALLOW_THREADS/
   Py_END_ALLOW_THREADS macros are acceptable.

   The return value is an opaque "handle" to the thread state when
176
   PyGILState_Ensure() was called, and must be passed to
177
   PyGILState_Release() to ensure Python is left in the same state. Even
178 179
   though recursive calls are allowed, these handles can *not* be shared -
   each unique call to PyGILState_Ensure must save the handle for its
180 181 182 183 184 185 186 187 188 189
   call to PyGILState_Release.

   When the function returns, the current thread will hold the GIL.

   Failure is a fatal error.
*/
PyAPI_FUNC(PyGILState_STATE) PyGILState_Ensure(void);

/* Release any resources previously acquired.  After this call, Python's
   state will be the same as it was prior to the corresponding
190
   PyGILState_Ensure() call (but generally this state will be unknown to
191 192
   the caller, hence the use of the GILState API.)

193
   Every call to PyGILState_Ensure must be matched by a call to
194 195 196 197 198
   PyGILState_Release on the same thread.
*/
PyAPI_FUNC(void) PyGILState_Release(PyGILState_STATE);

/* Helper/diagnostic function - get the current thread state for
199
   this thread.  May return NULL if no GILState API has been used
200
   on the current thread.  Note that the main thread always has such a
201
   thread-state, even if no auto-thread-state call has been made
202 203 204 205
   on the main thread.
*/
PyAPI_FUNC(PyThreadState *) PyGILState_GetThisThreadState(void);

206 207
#endif   /* #ifdef WITH_THREAD */

208 209 210
/* The implementation of sys._current_frames()  Returns a dict mapping
   thread id to that thread's current frame.
*/
211
#ifndef Py_LIMITED_API
212
PyAPI_FUNC(PyObject *) _PyThread_CurrentFrames(void);
213
#endif
214

215 216
/* Routines for advanced debuggers, requested by David Beazley.
   Don't use unless you know what you are doing! */
217
#ifndef Py_LIMITED_API
218 219 220 221
PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Head(void);
PyAPI_FUNC(PyInterpreterState *) PyInterpreterState_Next(PyInterpreterState *);
PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
222

223
typedef struct _frame *(*PyThreadFrameGetter)(PyThreadState *self_);
224
#endif
225

226
/* hook for PyEval_GetFrame(), requested for Psyco */
227
#ifndef Py_LIMITED_API
228
PyAPI_DATA(PyThreadFrameGetter) _PyThreadState_GetFrame;
229
#endif
230

231 232 233 234
#ifdef __cplusplus
}
#endif
#endif /* !Py_PYSTATE_H */