From 95c1cc89ed4802aeb613fd7f776dcb681a7de5d8 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 28 Oct 2025 08:20:10 -0400 Subject: [PATCH 1/4] Rename section for clarity on Py_IsFinalizing --- peps/pep-0788.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0788.rst b/peps/pep-0788.rst index b45e4f3324a..c18beb5684a 100644 --- a/peps/pep-0788.rst +++ b/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 ` currently recommend :c:func:`Py_IsFinalizing` to guard against termination of From 650c19c875bc62939e763dbe21ce3ff474e8dcfa Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 28 Oct 2025 08:27:28 -0400 Subject: [PATCH 2/4] Clarify non-releasing behavior --- peps/pep-0788.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/peps/pep-0788.rst b/peps/pep-0788.rst index c18beb5684a..a10fb5c7981 100644 --- a/peps/pep-0788.rst +++ b/peps/pep-0788.rst @@ -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`. @@ -395,7 +397,8 @@ Interpreter Views .. 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`. @@ -451,7 +454,9 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`. .. 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 From a3e6b5d8705f912882a0ff98e0400ba8d1a05f8c Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 28 Oct 2025 08:29:58 -0400 Subject: [PATCH 3/4] Fix contradicting text in PyInterpreterView_Copy() Also added double-spacing between functions. --- peps/pep-0788.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/peps/pep-0788.rst b/peps/pep-0788.rst index a10fb5c7981..0d71bd3ab36 100644 --- a/peps/pep-0788.rst +++ b/peps/pep-0788.rst @@ -373,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. @@ -385,6 +386,7 @@ Interpreter Views The caller must hold an :term:`attached thread state`. + .. c:function:: PyInterpreterView PyInterpreterView_Copy(PyInterpreterView view) Duplicate a view to an interpreter. @@ -392,8 +394,8 @@ Interpreter Views 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) @@ -403,6 +405,7 @@ Interpreter Views 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. @@ -432,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 @@ -452,6 +456,7 @@ 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. If this function is From 150d5b0cbc109ae3a49ee4f93f35d00e9a1bf226 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 28 Oct 2025 08:31:17 -0400 Subject: [PATCH 4/4] Fix incorrect name in Rejected Ideas --- peps/pep-0788.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0788.rst b/peps/pep-0788.rst index 0d71bd3ab36..d933316f97f 100644 --- a/peps/pep-0788.rst +++ b/peps/pep-0788.rst @@ -913,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 `_ to provide actual