Clarify the PyGILState variant in the docs...

as being an init, do things, finalizer trio where lots of stuff without the GIL
held can happen inbetween.  There might not be a GIL but when used in builds
where there is you don't want to hold it.

There's an internal recursion counter within the PyGILState APIs, if it goes to
0 on Release, any Python thread state that it created is destroyed.  We're
working around that.  Should I mention that internals detail?

Author: gpshead

Doc/c-api/threads.rst

@@ -257,20 +257,28 @@ exits::
 The equivalent with the :ref:`PyGILState API <gilstate>` keeps an *outer*
 :c:func:`PyGILState_Ensure` outstanding for the thread's lifetime, so
 nested Ensure/Release pairs never drop the internal nesting counter to
-zero::
+zero.
+
+In thread startup, pin the state and immediately detach so the thread
+does not hold the GIL while off doing non-Python work.  Stash ``outer``
+and ``saved`` somewhere that survives for the thread's lifetime (for
+example, in thread-local storage)::
 
-   /* Thread startup: create and pin the state. */
    PyGILState_STATE outer = PyGILState_Ensure();
-   PyThreadState *saved = PyEval_SaveThread();
+   PyThreadState *saved   = PyEval_SaveThread();
+
+Each subsequent call into Python from this thread reuses the pinned
+state; the inner Release decrements the nesting counter but does not
+destroy the thread state because the outer Ensure is still
+outstanding::
 
-   /* Per-call: the thread state already exists. */
    PyGILState_STATE inner = PyGILState_Ensure();
    result = CallSomeFunction();
    PyGILState_Release(inner);
 
-   /* ... many more calls ... */
+At thread shutdown, re-attach and drop the outer reference to destroy
+the thread state::
 
-   /* Thread shutdown: unpin and destroy the state. */
    PyEval_RestoreThread(saved);
    PyGILState_Release(outer);