Editorial pass

Author: ZeroIntensity

peps/pep-0788.rst

@@ -22,11 +22,10 @@ interpreter by preventing finalization. In particular:
 1. :c:type:`PyInterpreterGuard`, which prevents an interpreter
    from finalizing.
 2. :c:type:`PyInterpreterView`, which provides a thread-safe way to get an
-   interpreter guard for an interpreter without holding an
-   :term:`attached thread state`.
+   interpreter without holding an :term:`attached thread state`.
 3. :c:func:`PyThreadState_Ensure`, :c:func:`PyThreadState_EnsureFromView`,
    and :c:func:`PyThreadState_Release`, which are high-level APIs for
-   getting an attached thread state whilst in arbitrary native code (similar
+   getting an attached thread state while in arbitrary native code (similar
    to :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`).
 
 
@@ -75,8 +74,8 @@ Foreign threads hang during interpreter finalization
 ----------------------------------------------------
 
 Many large libraries might need to call Python code in highly asynchronous
-situations where the desired interpreter may be finalizing or deleted, but
-want to continue running code after invoking the interpreter. This desire has been
+situations where the desired interpreter may be finalizing or has already been finalized,
+but want to continue running code after invoking the interpreter. This desire has been
 `brought up by users <https://discuss.python.org/t/78850/>`_.
 For example, a callback that wants to call Python code might be invoked when:
 
@@ -122,7 +121,7 @@ Locks in native extensions can be unusable during finalization
 
 When acquiring locks in a native API, it's common (and often necessary)
 to release the GIL (or critical sections on the free-threaded build) to
-allow other code to execute during lock-aquisition.
+allow other code to execute during aquisition of the lock.
 This can be problematic during finalization, because threads holding locks might
 be hung. For example:
 
@@ -200,9 +199,8 @@ Interpreter guards
     function. The guard must eventually be closed with
     :c:func:`PyInterpreterGuard_Close`.
 
-    If the interpreter no longer exists or cannot safely run Python code,
-    or if the process is out of memory, this function returns ``NULL`` without
-    setting an exception.
+    If the interpreter no longer exists, is already finalizing, or out of memory,
+    then this function returns ``NULL`` without setting an exception.
 
     The caller does not need to hold an attached thread state.
 
@@ -215,7 +213,8 @@ Interpreter guards
     to enter finalization.
 
     After an interpreter guard is closed, it may not be used in
-    :c:func:`PyThreadState_Ensure`. Doing so is undefined behavior.
+    :c:func:`PyThreadState_Ensure`. Doing so will result in undefined
+    behavior.
 
     This function cannot fail, and the caller doesn't need to hold an
     attached thread state.
@@ -228,38 +227,41 @@ Interpreter views
 
     An opaque view of an interpreter.
 
-    This is a thread-safe way to access an interpreter that may have been
-    deleted or otherwise cannot execute in another thread.
+    This is a thread-safe way to access an interpreter that may have be
+    finalizing or already destroyed.
 
 
 .. c:function:: PyInterpreterView *PyInterpreterView_FromCurrent(void)
 
     Create a view to the current interpreter.
 
-    This function is generally meant to be used in tandem with
-    :c:func:`PyInterpreterGuard_FromView`.
+    This function is generally meant to be used alongside
+    :c:func:`PyInterpreterGuard_FromView` or :c:func:`PyThreadState_EnsureFromView`.
 
     On success, this function returns a view to the current interpreter; on
-    failure, it returns ``0`` with an exception set.
+    failure, it returns ``NULL`` with an exception set.
 
     The caller must hold an attached thread state.
 
 
 .. c:function:: void PyInterpreterView_Close(PyInterpreterView *view)
 
     Delete an interpreter view. If an interpreter view is never closed, the
-    view's memory will never be freed.
+    view's memory will never be freed, but there are no other consequences.
+    (In contrast, forgetting to close a guard will infinitely hang the main
+    thread during finalization.)
 
     This function cannot fail, and the caller doesn't need to hold an
     attached thread state.
 
 
 .. c:function:: PyInterpreterView *PyInterpreterView_FromMain()
 
-    Create a view for the "main" interpreter.
+    Create a view for the main interpreter (the first and default
+    interpreter in a Python process).
 
     On success, this function returns a view to the main
-    interpreter; on failure, it returns ``0`` without an exception set.
+    interpreter; on failure, it returns ``NULL`` without an exception set.
     Failure indicates that the process is out of memory.
 
     The caller does not need to hold an attached thread state.
@@ -301,9 +303,10 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
     for *guard*. It is then attached and marked as owned by ``PyThreadState_Ensure``.
 
     This function will return ``NULL`` to indicate a memory allocation failure, and
-    otherwise return an opaque view to the thread state that was previously attached
+    otherwise return a pointer to the thread state that was previously attached
     (which might have been ``NULL``, in which case an non-``NULL`` sentinel value is
-    returned instead to differentiate between failure).
+    returned instead to differentiate between failure -- this means that this function
+    will sometimes return an invalid ``PyThreadState`` pointer).
 
     To visualize, this function is roughly equivalent to the following:
 
@@ -347,8 +350,8 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
 
     *view* must not be ``NULL``. If the interpreter referenced by *view* has been
     finalized or is currently finalizing, then this function returns ``NULL`` without
-    setting. This function may also return ``NULL`` to indicate that the process is
-    out of memory.
+    setting an exception. This function may also return ``NULL`` to indicate that the
+    process is out of memory.
 
     The interpreter referenced by *view* will be implicitly guarded. The
     guard will be released upon the corresponding :c:func:`PyThreadState_Release`
@@ -388,7 +391,8 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
     for each call to ``PyThreadState_Ensure``.
 
     This function will decrement an internal counter on the attached thread state. If
-    this counter ever reaches below zero, this function emits a fatal error.
+    this counter ever reaches below zero, this function emits a fatal error (via
+    :c:func:`Py_FatalError`).
 
     If the attached thread state is owned by ``PyThreadState_Ensure``, then the
     attached thread state will be deallocated and deleted upon the internal counter
@@ -483,12 +487,13 @@ The term "GIL" in ``PyGILState`` is confusing for free-threading
 
 This PEP uses the prefix ``PyThreadState`` instead of ``PyGILState``
 is because the term "GIL" in the C API is semantically misleading.
-Again, in modern Python versions, :c:func:`PyGILState_Ensure` is about
+In modern Python versions, :c:func:`PyGILState_Ensure` is about
 attaching a thread state, which only incidentally acquires the GIL.
 
 An attached thread state is still required to invoke the C API on the free-threaded
-build, but with a name that contains "GIL", it is often confused to why it is
-still needed.
+build, but with a name that contains "GIL", it is often confusing to why calls to
+``PyGILState_Ensure`` and ``PyGILState_Release`` are still needed from foreign
+threads.
 
 
 Finalization behavior for ``PyGILState_Ensure`` cannot change
@@ -499,7 +504,7 @@ There will always have to be a point in a Python program where
 If the interpreter is long dead, then Python obviously can't give a
 thread a way to invoke it. Unfortunately, :c:func:`PyGILState_Ensure`
 doesn't have any meaningful way to return a failure, so it has no choice
-but to terminate the thread or emit a fatal error. For example, this
+but to terminate (or hang) the thread or emit a fatal error. For example, this
 was discussed in
 `python/cpython#124622 <https://github.com/python/cpython/issues/124622>`_:
 
@@ -538,10 +543,10 @@ For example:
 6. ``PyMem_Realloc`` doesn't own the buffer in the list; crash!
 
 The author of this PEP acknowledges that subinterpreters are not
-currently a popular use-case, but strongly believes that a proposal
-introducing a new C API for attaching and detaching thread states
-should also fix this issue; otherwise, the new API may have to be
-deprecated in the future in order to support subinterpreters.
+currently a popular use-case, but believes that it would be
+difficult to design a new API that does not also improve the situtation
+for subinterpreters. Opting out of subinterpreter is support is available
+through :c:func:`PyThreadView_FromMain`.
 
 
 Backwards Compatibility
@@ -551,8 +556,8 @@ This PEP specifies no breaking changes.
 
 Existing code **does not** have to be rewritten to use the new APIs from
 this PEP, and all ``PyGILState`` APIs will continue to work. Use of ``PyGILState``
-APIs will not emit any form of warning during compilation or at runtime. The APIs
-will merely not be developed further.
+APIs will not emit any form of warning during compilation or at runtime. There
+will merely not be any *new* ``PyGILState`` APIs in future versions of Python.
 
 
 Security Implications
@@ -565,9 +570,7 @@ How to Teach This
 =================
 
 As with all C API functions, all the new APIs in this PEP will be documented
-in the C API documentation, ideally under the ":ref:`python:gilstate`" section.
-The existing ``PyGILState`` documentation should be updated accordingly to point
-to the new APIs.
+in the C API documentation.
 
 
 Examples
@@ -623,11 +626,11 @@ This example shows how to acquire a C lock in a Python method defined from C.
 
 If this were called from a daemon thread, the interpreter could hang the
 thread while reattaching its thread state, leaving us with the lock held,
-in which case, any future finalizer that attempts to acquire the lock would
-be deadlocked.
+in which case any future finalizer that attempts to acquire the lock would
+deadlock.
 
 By guarding the interpreter while the lock is held, we can be sure that the
-thread won't be clobbered.
+thread won't be clobbered or hung:
 
 .. code-block:: c
 
@@ -885,7 +888,7 @@ Hard deprecating ``PyGILState``
 
 This PEP used to specify a "hard" deprecation of all APIs in the
 ``PyGILState`` family, with a planned removal in Python 3.20 (five years)
-of Python 3.25 (ten years).
+or Python 3.25 (ten years).
 
 This was eventually decided against, because while it is acknowledged that
 ``PyGILState_Ensure`` does have some fundamental flaws, it has worked for over
@@ -894,8 +897,7 @@ for Python's ecosystem.
 
 Even with the finalization issues addressed by this PEP, a large majority of
 existing code that uses ``PyGILState_Ensure`` currently works, and will continue
-to work regardless of whether new APIs exist. To quote :pep:`20`: "practicality
-beats purity".
+to work regardless of whether new APIs exist.
 
 
 Interpreter reference counting