PEP 788: Final tweaks to improve clarity

peps/pep-0788.rst

@@ -122,8 +122,8 @@ This means that any non-Python thread may be terminated at any point, which
 severely limits users who want to do more than just execute Python
 code in their stream of calls.
 
-``Py_IsFinalizing`` Is Not Atomic
-*********************************
+``Py_IsFinalizing`` Cannot Be Used Atomically
+*********************************************
 
 Due to the problem mentioned previously, the :ref:`docs <python:gilstate>`
 currently recommend :c:func:`Py_IsFinalizing` to guard against termination of
@@ -354,7 +354,9 @@ Interpreter Guards
 .. c:function:: void PyInterpreterGuard_Close(PyInterpreterGuard guard)
 
     Destroy an interpreter guard, allowing the interpreter to enter
-    finalization if no other guards remain.
+    finalization if no other guards remain. If an interpreter guard
+    is never closed, the interpreter will infinitely wait when trying
+    to enter finalization.
 
     This function cannot fail, and the caller doesn't need to hold an
     :term:`attached thread state`.
@@ -371,6 +373,7 @@ Interpreter Views
 
     This type is guaranteed to be pointer-sized.
 
+
 .. c:function:: PyInterpreterView PyInterpreterView_FromCurrent(void)
 
     Create a view to the current interpreter.
@@ -383,23 +386,26 @@ Interpreter Views
 
     The caller must hold an :term:`attached thread state`.
 
+
 .. c:function:: PyInterpreterView PyInterpreterView_Copy(PyInterpreterView view)
 
     Duplicate a view to an interpreter.
 
     On success, this function returns a non-zero copy of *view*; on failure,
     it returns ``0`` without an exception set.
 
-    This function cannot fail, and the caller doesn't need to hold an
-    :term:`attached thread state`.
+    The caller does not need to hold an :term:`attached thread state`.
+
 
 .. c:function:: void PyInterpreterView_Close(PyInterpreterView view)
 
-    Delete an interpreter view.
+    Delete an interpreter view. If an interpreter view is never closed, the
+    view's memory will never be freed.
 
     This function cannot fail, and the caller doesn't need to hold an
     :term:`attached thread state`.
 
+
 .. c:function:: PyInterpreterView PyUnstable_InterpreterView_FromDefault()
 
     Create a view for an arbitrary "main" interpreter.
@@ -429,6 +435,7 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
 
     This type is guaranteed to be pointer-sized.
 
+
 .. c:function:: PyThreadView PyThreadState_Ensure(PyInterpreterGuard guard)
 
     Ensure that the thread has an :term:`attached thread state` for the
@@ -449,9 +456,12 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
     Return a non-zero thread view of the old thread state on success, and
     ``0`` on failure.
 
+
 .. c:function:: void PyThreadState_Release(PyThreadView view)
 
-    Release a :c:func:`PyThreadState_Ensure` call.
+    Release a :c:func:`PyThreadState_Ensure` call. If this function is
+    not called, the thread state created by :c:func:`PyThreadState_Ensure`,
+    if any, will leak.
 
     The :term:`attached thread state` before the corresponding
     :c:func:`PyThreadState_Ensure` call is guaranteed to be restored upon
@@ -903,8 +913,8 @@ hurt the proposal's goals:
 
 .. _pep-788-activate-deactivate-instead:
 
-Exposing an ``Activate``/``Deactivate`` API Instead of ``Ensure``/``Clear``
----------------------------------------------------------------------------
+Exposing an ``Activate``/``Deactivate`` API Instead of ``Ensure``/``Release``
+-----------------------------------------------------------------------------
 
 In prior discussions of this API, it was
 `suggested <https://discuss.python.org/t/83959/2>`_ to provide actual