\begin{cfuncdesc}{PyGILState_STATE}{PyGILState_Ensure}{}

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

by a thread as long as each call is matched with a call to

\cfunction{PyGILState_Release()}.

In general, other thread-related APIs may

be used between \cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()} calls as long as the

thread state is restored to its previous state before the Release().

For example, normal usage of the \csimplemacro{Py_BEGIN_ALLOW_THREADS}

and \csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.

The return value is an opaque "handle" to the thread state when

\cfunction{PyGILState_Acquire()} was called, and must be passed to

\cfunction{PyGILState_Release()} to ensure Python is left in the same

state. Even though recursive calls are allowed, these handles

\emph{cannot} be shared - each unique call to

\cfunction{PyGILState_Ensure} must save the handle for its call to

\cfunction{PyGILState_Release}.

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

Failure is a fatal error.

\versionadded{2.3}

\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyGILState_Release}{PyGILState_STATE}

Release any resources previously acquired. After this call, Python's

state will be the same as it was prior to the corresponding

\cfunction{PyGILState_Ensure} call (but generally this state will be unknown to

the caller, hence the use of the GILState API.)

Every call to \cfunction{PyGILState_Ensure()} must be matched by a call to

\cfunction{PyGILState_Release()} on the same thread.

\versionadded{2.3}

\end{cfuncdesc}