Clean up discussion of new C thread idiom

(closes SF patch #1031233; modified)

diff --git a/Doc/api/init.tex b/Doc/api/init.tex
index 764c93275e20aecece062a4b9591101fb1aa2032..e8d35838c9c5407c68fd19250b5515922815100d 100644 (file)
--- a/Doc/api/init.tex
+++ b/Doc/api/init.tex
@@ -455,19 +455,10 @@ Python/C API.  When they are done, they should reset the thread state
 pointer, release the lock, and finally free their thread state data
 structure.
 
-When creating a thread data structure, you need to provide an
-interpreter state data structure.  The interpreter state data
-structure holds global data that is shared by all threads in an
-interpreter, for example the module administration
-(\code{sys.modules}).  Depending on your needs, you can either create
-a new interpreter state data structure, or share the interpreter state
-data structure used by the Python main thread (to access the latter,
-you must obtain the thread state and access its \member{interp} member;
-this must be done by a thread that is created by Python or by the main
-thread after Python is initialized).
-
-Assuming you have access to an interpreter object, the typical idiom
-for calling into Python from a C thread is
+Beginning with version 2.3, threads can now take advantage of the 
+\cfunction{PyGILState_*()} functions to do all of the above
+automatically.  The typical idiom for calling into Python from a C
+thread is now:
 
 \begin{verbatim}
     PyGILState_STATE gstate;
@@ -481,6 +472,13 @@ for calling into Python from a C thread is
     PyGILState_Release(gstate);
 \end{verbatim}
 
+Note that the \cfunction{PyGILState_*()} functions assume there is only
+one global  interpreter (created automatically by
+\cfunction{Py_Initialize()}).  Python still supports the creation of
+additional interpreters  (using \cfunction{Py_NewInterpreter()}), but
+mixing multiple interpreters and the \cfunction{PyGILState_*()} API is
+unsupported.
+
 \begin{ctypedesc}{PyInterpreterState}
   This data structure represents the state shared by a number of
   cooperating threads.  Threads belonging to the same interpreter