15f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles)# Thread and interpreter state structures and their interfaces 25f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 35f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles)from cpython.ref cimport PyObject 45f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 55f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles)cdef extern from "Python.h": 65f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 75f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # We make these an opague types. If the user wants specific attributes, 85f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # they can be declared manually. 95f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 105f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) ctypedef struct PyInterpreterState: 115f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) pass 125f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 135f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) ctypedef struct PyThreadState: 145f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) pass 155f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 165f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) ctypedef struct PyFrameObject: 175f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) pass 185f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 195f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # This is not actually a struct, but make sure it can never be coerced to 205f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # an int or used in arithmetic expressions 215f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) ctypedef struct PyGILState_STATE 225f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 235f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # The type of the trace function registered using PyEval_SetProfile() and 245f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # PyEval_SetTrace(). 255f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # Py_tracefunc return -1 when raising an exception, or 0 for success. 265f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) ctypedef int (*Py_tracefunc)(PyObject *, PyFrameObject *, int, PyObject *) 275f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 285f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # The following values are used for 'what' for tracefunc functions 295f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) enum: 305f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyTrace_CALL 315f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyTrace_EXCEPTION 325f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyTrace_LINE 335f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyTrace_RETURN 345f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyTrace_C_CALL 355f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyTrace_C_EXCEPTION 365f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyTrace_C_RETURN 375f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 385f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 395f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyInterpreterState * PyInterpreterState_New() 405f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) void PyInterpreterState_Clear(PyInterpreterState *) 415f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) void PyInterpreterState_Delete(PyInterpreterState *) 425f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 435f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyThreadState * PyThreadState_New(PyInterpreterState *) 445f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) void PyThreadState_Clear(PyThreadState *) 455f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) void PyThreadState_Delete(PyThreadState *) 465f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 475f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyThreadState * PyThreadState_Get() 485f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyThreadState * PyThreadState_Swap(PyThreadState *) 495f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyObject * PyThreadState_GetDict() 505f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) int PyThreadState_SetAsyncExc(long, PyObject *) 515f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 525f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # Ensure that the current thread is ready to call the Python 535f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # C API, regardless of the current state of Python, or of its 545f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # thread lock. This may be called as many times as desired 555f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # by a thread so long as each call is matched with a call to 565f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # PyGILState_Release(). In general, other thread-state APIs may 575f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # be used between _Ensure() and _Release() calls, so long as the 585f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # thread-state is restored to its previous state before the Release(). 595f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # For example, normal use of the Py_BEGIN_ALLOW_THREADS/ 605f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # Py_END_ALLOW_THREADS macros are acceptable. 615f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 625f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # The return value is an opaque "handle" to the thread state when 635f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # PyGILState_Ensure() was called, and must be passed to 645f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # PyGILState_Release() to ensure Python is left in the same state. Even 655f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # though recursive calls are allowed, these handles can *not* be shared - 665f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # each unique call to PyGILState_Ensure must save the handle for its 675f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # call to PyGILState_Release. 685f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 695f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # When the function returns, the current thread will hold the GIL. 705f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 715f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # Failure is a fatal error. 725f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyGILState_STATE PyGILState_Ensure() 735f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 745f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # Release any resources previously acquired. After this call, Python's 755f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # state will be the same as it was prior to the corresponding 765f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # PyGILState_Ensure() call (but generally this state will be unknown to 775f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # the caller, hence the use of the GILState API.) 785f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 795f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # Every call to PyGILState_Ensure must be matched by a call to 805f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # PyGILState_Release on the same thread. 815f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) void PyGILState_Release(PyGILState_STATE) 825f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) 835f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # Routines for advanced debuggers, requested by David Beazley. 845f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) # Don't use unless you know what you are doing! 855f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyInterpreterState * PyInterpreterState_Head() 865f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyInterpreterState * PyInterpreterState_Next(PyInterpreterState *) 875f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *) 885f1c94371a64b3196d4be9466099bb892df9b88eTorne (Richard Coles) PyThreadState * PyThreadState_Next(PyThreadState *) 89