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