[Python-checkins] python/dist/src/Doc/api init.tex,1.16,1.17

[akuchling at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/api
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22793

Modified Files:
	init.tex 
Log Message:
[Bug #987835] Add documentation from PEP 311.  (Untested TeX code.)

Index: init.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/init.tex,v
retrieving revision 1.16
retrieving revision 1.17
diff -C2 -d -r1.16 -r1.17
*** init.tex	24 Mar 2004 21:57:07 -0000	1.16
--- init.tex	10 Jul 2004 13:31:18 -0000	1.17
***************
*** 700,703 ****
--- 700,739 ----
  \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}}