diff --git a/peps/pep-0788.rst b/peps/pep-0788.rst index b45e4f3324a..d933316f97f 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 @@ -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,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. @@ -390,16 +394,18 @@ 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) - 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 `_ to provide actual