Clarify some things.

Author: ZeroIntensity

peps/pep-0788.rst

@@ -270,46 +270,23 @@ updated to switch over to terms like
 :term:`"global interpreter lock" <global interpreter lock>`, so this namespace
 seems to fit well for this PEP.
 
-Specification
-=============
-
-Interpreter reference counting
-------------------------------
-
-Internally, the interpreter will have to keep track of a reference count
-field, which will determine when the interpreter state is actually
-deallocated. This is done to prevent use-after-free crashes in
-:c:func:`PyThreadState_Ensure` for interpreters with short lifetimes.
-
-An interpreter state returned by :c:func:`Py_NewInterpreter` (or really,
-:c:func:`PyInterpreterState_New`) will start with a reference count of 1, and
-:c:func:`PyInterpreterState_Delete` will decrement the reference count. If the
-new reference count is zero, :c:func:`PyInterpreterState_Delete` will
-deallocate the interpreter state. However, the reference count will *not*
-prevent the interpreter from finalizing.
-
-.. c:function:: PyInterpreterState *PyInterpreterState_Hold(void)
-
-    Similar to :c:func:`PyInterpreterState_Get`, but returns a strong
-    reference to the interpreter (meaning, it has its reference count
-    incremented by one, allowing the returned interpreter state to be safely
-    accessed by another thread).
-
-    This function is generally meant to be used in tandem with
-    :c:func:`PyThreadState_Ensure`.
-
-    The caller must have an :term:`attached thread state`, and cannot return
-    ``NULL``. Failures are always a fatal error.
-
-
-.. c:function:: void PyInterpreterState_Release(PyInterpreterState *interp)
+Preventing interpreter finalization with references
+---------------------------------------------------
 
-    Decrement the reference count of the interpreter, as was incremented by
-    :c:func:`PyInterpreterState_Hold`.
+Several iterations of this API have taken an approach where
+:c:func:`PyThreadState_Ensure` can return a failure based on the state of
+the interpreter. Instead, this PEP takes an approach where an interpreter
+keeps track of the number of non-daemon threads, which inherently prevents
+it from beginning finalization.
 
-    This function cannot fail, other than with a fatal error. The caller must
-    have an :term:`attached thread state` for *interp*.
+The main upside with this approach is that there's more consistency with
+attaching threads. Using an interpreter reference from the calling thread
+keeps the interpreter from finalizing before the thread starts, ensuring
+that it always works. An approach that were to return a failure based on
+the start-time of the thread could cause spurious issues.
 
+Specification
+=============
 
 Daemon and non-daemon threads
 -----------------------------
@@ -344,8 +321,43 @@ remain daemon by default.
     :attr:`threading.Thread.daemon`.
 
     Return zero on success, non-zero *without* an exception set on failure.
-    Failure generally means that threads have already finalized for the
-    current interpreter.
+
+Interpreter reference counting
+------------------------------
+
+Internally, the interpreter will have to keep track of the number of
+non-daemon native threads, which will determine when the interpreter can
+finalize. This is done to prevent use-after-free crashes in
+:c:func:`PyThreadState_Ensure` for interpreters with short lifetimes, and
+to remove needless layers of synchronization between the calling thread and
+the started thread.
+
+An interpreter state returned by :c:func:`Py_NewInterpreter` (or really,
+:c:func:`PyInterpreterState_New`) will start with a native thread countdown.
+For simplicity's sake, this will be referred to as a reference count.
+A non-zero reference count prevents the interpreter from finalizing.
+
+.. c:function:: PyInterpreterState *PyInterpreterState_Hold(void)
+
+    Similar to :c:func:`PyInterpreterState_Get`, but returns a strong
+    reference to the interpreter (meaning, it has its reference count
+    incremented by one, allowing the returned interpreter state to be safely
+    accessed by another thread, because it will be prevented from finalizing).
+
+    This function is generally meant to be used in tandem with
+    :c:func:`PyThreadState_Ensure`.
+
+    The caller must have an :term:`attached thread state`, and cannot return
+    ``NULL``. Failures are always a fatal error.
+
+
+.. c:function:: void PyInterpreterState_Release(PyInterpreterState *interp)
+
+    Decrement the reference count of the interpreter, as was incremented by
+    :c:func:`PyInterpreterState_Hold`.
+
+    This function cannot fail, other than with a fatal error. The caller must
+    have an :term:`attached thread state` for *interp*.
 
 Ensuring and releasing thread states
 ------------------------------------