Commit MvL's doc patch for SF bug #221327. This adds an example of

calling into Python from a C thread.

diff --git a/Doc/api/init.tex b/Doc/api/init.tex
index 663c2fe1d9510b8381cdceffca7f64ca7df3ee3e..f0ca287e0452c9aa05234dce006ee553b34bb2c2 100644 (file)
--- a/Doc/api/init.tex
+++ b/Doc/api/init.tex
@@ -466,6 +466,28 @@ 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
+
+\begin{verbatim}
+    PyThreadState *tstate;
+    PyObject *result;
+
+    /* interp is your reference to an interpreter object. */
+    tstate = PyThreadState_New(interp);
+    PyEval_AcquireThread(tstate);
+
+    /* Perform Python actions here.  */
+    result = CallSomeFunction();
+    /* evaluate result */
+
+    /* Release the thread. No Python API allowed beyond this point. */
+    PyEval_ReleaseThread(tstate);
+
+    /* You can either delete the thread state, or save it
+       until you need it the next time. */
+    PyThreadState_Delete(tstate);
+\end{verbatim}
 
 \begin{ctypedesc}{PyInterpreterState}
   This data structure represents the state shared by a number of