Add a whatsnew entry.

Author: ZeroIntensity

Doc/c-api/interp-lifecycle.rst

@@ -604,6 +604,8 @@ which led to other issues (see the warning note at
 Gross? Yes. Starting in Python 3.15, there are a number of C APIs that make
 it possible to avoid these issues by temporarily preventing finalization:
 
+.. _interpreter-guards:
+
 .. seealso::
 
    :pep:`788`
@@ -703,6 +705,8 @@ it possible to avoid these issues by temporarily preventing finalization:
    .. versionadded:: next
 
 
+.. _interpreter-views:
+
 Interpreter views
 -----------------
 

Doc/c-api/threads.rst

@@ -61,9 +61,9 @@ as in a :c:macro:`Py_BEGIN_ALLOW_THREADS` block or in a fresh thread, will the
 thread not have an attached thread state.
 If uncertain, check if :c:func:`PyThreadState_GetUnchecked` returns ``NULL``.
 
-If it turns out that you do need to create a thread state, call :c:func:`PyThreadState_New`
-followed by :c:func:`PyThreadState_Swap`, or use the dangerous
-:c:func:`PyGILState_Ensure` function.
+If it turns out that you do need to create a thread state, it is recommended to
+use :c:func:`PyThreadState_Ensure` or :c:func:`PyThreadState_EnsureFromView`,
+which will manage the thread state for you.
 
 
 .. _detaching-thread-state:
@@ -248,6 +248,11 @@ Some notes about this:
 .. seealso::
    :pep:`788`
 
+.. _c-api-attach-detach:
+
+Attaching/detaching thread states
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. c:function:: PyThreadState *PyThreadState_Ensure(PyInterpreterGuard *guard)
 
    Ensure that the thread has an attached thread state for the

Doc/howto/free-threading-extensions.rst

@@ -218,13 +218,15 @@ Thread State and GIL APIs
 Python provides a set of functions and macros to manage thread state and the
 GIL, such as:
 
+* :c:func:`PyThreadState_Ensure`, :c:func:`PyThreadState_EnsureFromView`,
+  and :c:func:`PyThreadState_Release`
 * :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`
 * :c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`
 * :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS`
 
 These functions should still be used in the free-threaded build to manage
 thread state even when the :term:`GIL` is disabled.  For example, if you
-create a thread outside of Python, you must call :c:func:`PyGILState_Ensure`
+create a thread outside of Python, you must call :c:func:`PyThreadState_Ensure`
 before calling into the Python API to ensure that the thread has a valid
 Python thread state.
 

Doc/whatsnew/3.15.rst

@@ -86,6 +86,7 @@ Summary -- Release highlights
 * :pep:`782`: :ref:`A new PyBytesWriter C API to create a Python bytes object
   <whatsnew315-pybyteswriter>`
 * :pep:`803`: :ref:`Stable ABI for Free-Threaded Builds <whatsnew315-abi3t>`
+* :pep:`788`: :ref:`Protection against finalization in the C API <whatsnew315-c-api-interpreter-finalization>`
 * :ref:`The JIT compiler has been significantly upgraded <whatsnew315-jit>`
 * :ref:`Improved error messages <whatsnew315-improved-error-messages>`
 * :ref:`The official Windows 64-bit binaries now use the tail-calling interpreter
@@ -446,6 +447,38 @@ If not using a build tool -- or when writing such a tool -- you can select
 ``abi3t`` by setting the macro :c:macro:`!Py_TARGET_ABI3T` as discussed
 in :ref:`abi3-compiling`.
 
+.. _whatsnew315-c-api-interpreter-finalization:
+
+:pep:`788`: Protecting the C API from interpreter finalization
+--------------------------------------------------------------
+
+In the C API, :term:`interpreter finalization <interpreter shutdown>` can be
+problematic for many extensions, because :term:`attaching <attached thread
+state>` a thread state will permanently hang the thread, resulting in deadlocks
+and other spurious issues. Additionally, it has historically been impossible
+to atomically check whether an interpreter is alive, leading to crashes
+when a thread concurrently deletes an interpreter while another thread is
+trying to attach to it.
+
+There are now several new suites of APIs to circumvent these problems:
+
+* :ref:`Interpreter guards <interpreter-views>`, which prevent an interpreter
+  from finalizing.
+* :ref:`Interpreter views <interpreter-guards>`, which allow thread-safe access
+  to an interpreter that may be concurrently finalizing or deleted.
+* :ref:`New APIs <c-api-attach-detach>` to automatically attach and detach
+  thread states that come with built-in protection against finalization.
+
+In addition, APIs in the ``PyGILState`` family (most notably
+:c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`) have been
+:term:`soft deprecated`. There is **no** plan to remove them, and existing
+code will continue to work, but there will be no new ``PyGILState`` APIs
+in future versions of Python.
+
+.. seealso:: :pep:`788` for further details.
+
+(Contributed by Peter Bierma in :gh:`149101`.)
+
 
 .. _whatsnew315-improved-error-messages: