[Bug #987835] Add documentation from PEP 311. (Untested TeX code.)

Doc/api/init.tex

@@ -699,6 +699,42 @@ interpreter lock has been created.
   \versionadded{2.3}
 \end{cfuncdesc}
 
+\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}
+
 
 \section{Profiling and Tracing \label{profiling}}