1# Thread and interpreter state structures and their interfaces
2
3from cpython.ref cimport PyObject
4
5cdef extern from "Python.h":
6
7    # We make these an opague types. If the user wants specific attributes,
8    # they can be declared manually.
9
10    ctypedef struct PyInterpreterState:
11        pass
12
13    ctypedef struct PyThreadState:
14        pass
15
16    ctypedef struct PyFrameObject:
17        pass
18
19    # This is not actually a struct, but make sure it can never be coerced to
20    # an int or used in arithmetic expressions
21    ctypedef struct PyGILState_STATE
22
23    # The type of the trace function registered using PyEval_SetProfile() and
24    # PyEval_SetTrace().
25    # Py_tracefunc return -1 when raising an exception, or 0 for success.
26    ctypedef int (*Py_tracefunc)(PyObject *, PyFrameObject *, int, PyObject *)
27
28    # The following values are used for 'what' for tracefunc functions
29    enum:
30        PyTrace_CALL
31        PyTrace_EXCEPTION
32        PyTrace_LINE
33        PyTrace_RETURN
34        PyTrace_C_CALL
35        PyTrace_C_EXCEPTION
36        PyTrace_C_RETURN
37
38
39    PyInterpreterState * PyInterpreterState_New()
40    void PyInterpreterState_Clear(PyInterpreterState *)
41    void PyInterpreterState_Delete(PyInterpreterState *)
42
43    PyThreadState * PyThreadState_New(PyInterpreterState *)
44    void PyThreadState_Clear(PyThreadState *)
45    void PyThreadState_Delete(PyThreadState *)
46
47    PyThreadState * PyThreadState_Get()
48    PyThreadState * PyThreadState_Swap(PyThreadState *)
49    PyObject * PyThreadState_GetDict()
50    int PyThreadState_SetAsyncExc(long, PyObject *)
51
52    # Ensure that the current thread is ready to call the Python
53    # C API, regardless of the current state of Python, or of its
54    # thread lock.  This may be called as many times as desired
55    # by a thread so long as each call is matched with a call to
56    # PyGILState_Release().  In general, other thread-state APIs may
57    # be used between _Ensure() and _Release() calls, so long as the
58    # thread-state is restored to its previous state before the Release().
59    # For example, normal use of the Py_BEGIN_ALLOW_THREADS/
60    # Py_END_ALLOW_THREADS macros are acceptable.
61
62    # The return value is an opaque "handle" to the thread state when
63    # PyGILState_Ensure() was called, and must be passed to
64    # PyGILState_Release() to ensure Python is left in the same state. Even
65    # though recursive calls are allowed, these handles can *not* be shared -
66    # each unique call to PyGILState_Ensure must save the handle for its
67    # call to PyGILState_Release.
68
69    # When the function returns, the current thread will hold the GIL.
70
71    # Failure is a fatal error.
72    PyGILState_STATE PyGILState_Ensure()
73
74    # Release any resources previously acquired.  After this call, Python's
75    # state will be the same as it was prior to the corresponding
76    # PyGILState_Ensure() call (but generally this state will be unknown to
77    # the caller, hence the use of the GILState API.)
78
79    # Every call to PyGILState_Ensure must be matched by a call to
80    # PyGILState_Release on the same thread.
81    void PyGILState_Release(PyGILState_STATE)
82
83    # Routines for advanced debuggers, requested by David Beazley.
84    # Don't use unless you know what you are doing!
85    PyInterpreterState * PyInterpreterState_Head()
86    PyInterpreterState * PyInterpreterState_Next(PyInterpreterState *)
87    PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *)
88    PyThreadState * PyThreadState_Next(PyThreadState *)
89