Docs: fix stale and incorrect free-threading statements

* The extensions HOWTO claimed the free-threaded build does not support the
  stable ABI; 3.15 added abi3t.
* The library FAQ described GIL-based atomicity and the GIL removal as
  future work without mentioning the free-threaded build.
* threading no longer describes free threading as unavailable.
* The free-threading HOWTO's immortalization and deferred reference counting
  lists were incomplete.

Author: johng

Doc/faq/library.rst

@@ -362,8 +362,8 @@ class provides a featureful interface.
 What kinds of global value mutation are thread-safe?
 ----------------------------------------------------
 
-A :term:`global interpreter lock` (GIL) is used internally to ensure that only one
-thread runs in the Python VM at a time.  In general, Python offers to switch
+In the default build of CPython, a :term:`global interpreter lock` (GIL) is
+used internally to ensure that only one thread runs in the Python VM at a time.  In general, Python offers to switch
 among threads only between bytecode instructions; how frequently it switches can
 be set via :func:`sys.setswitchinterval`.  Each bytecode instruction and
 therefore all the C implementation code reached from each instruction is
@@ -401,6 +401,17 @@ Operations that replace other objects may invoke those other objects'
 affect things.  This is especially true for the mass updates to dictionaries and
 lists.  When in doubt, use a mutex!
 
+.. note::
+
+   The above relies on the GIL.  In the :term:`free-threaded <free threading>`
+   build, where the GIL is disabled, threads can run bytecode in parallel and
+   a bytecode instruction is not atomic in general.  Built-in types such as
+   :class:`list`, :class:`dict` and :class:`set` use internal locks so that
+   individual operations on them still behave atomically, but compound
+   operations such as ``D[x] = D[x] + 1`` remain unsafe.  See
+   :ref:`threadsafety` for the guarantees provided for built-in types and
+   :ref:`freethreading-python-howto` for more information.
+
 
 Can't we get rid of the Global Interpreter Lock?
 ------------------------------------------------
@@ -410,14 +421,14 @@ deployment on high-end multiprocessor server machines, because a multi-threaded
 Python program effectively only uses one CPU, due to the insistence that
 (almost) all Python code can only run while the GIL is held.
 
-With the approval of :pep:`703` work is now underway to remove the GIL from the
-CPython implementation of Python.  Initially it will be implemented as an
-optional compiler flag when building the interpreter, and so separate
-builds will be available with and without the GIL.  Long-term, the hope is
-to settle on a single build, once the performance implications of removing the
-GIL are fully understood.  Python 3.13 is likely to be the first release
-containing this work, although it may not be completely functional in this
-release.
+With the approval of :pep:`703` the GIL can be disabled in CPython.  This is
+implemented as an optional compile-time flag (:option:`--disable-gil`), so
+separate builds are available with and without the GIL.  The first release
+containing this work was Python 3.13, where it was experimental; the
+:term:`free-threaded <free threading>` build is officially supported as of
+Python 3.14.  See :ref:`freethreading-python-howto` for details.  Long-term,
+the hope is to settle on a single build, once the performance implications of
+removing the GIL are fully understood.
 
 The current work to remove the GIL is based on a
 `fork of Python 3.9 with the GIL removed <https://github.com/colesbury/nogil>`_

Doc/howto/free-threading-extensions.rst

@@ -425,17 +425,24 @@ The wheels, shared libraries, and binaries are indicated by a ``t`` suffix.
 Limited C API and Stable ABI
 ............................
 
-The free-threaded build does not currently support the
+Starting with Python 3.15, the free-threaded build supports the
+:ref:`Limited C API <limited-c-api>` and a variant of the stable ABI called
+``abi3t``.  See :ref:`abi3t-migration-howto` for how to target it, and
+:ref:`stable-abi` for how ``abi3t`` relates to ``abi3``.
+
+The free-threaded builds of Python 3.14 and older do not support the
 :ref:`Limited C API <limited-c-api>` or the stable ABI.  If you use
 `setuptools <https://setuptools.pypa.io/en/latest/setuptools.html>`_ to build
-your extension and currently set ``py_limited_api=True`` you can use
+your extension for these versions and currently set ``py_limited_api=True``,
+you can use
 ``py_limited_api=not sysconfig.get_config_var("Py_GIL_DISABLED")`` to opt out
 of the limited API when building with the free-threaded build.
 
 .. note::
-    You will need to build separate wheels specifically for the free-threaded
-    build.  If you currently use the stable ABI, you can continue to build a
-    single wheel for multiple non-free-threaded Python versions.
+    Unless you target ``abi3t``, you will need to build separate wheels
+    specifically for the free-threaded build.  If you use the ``abi3`` stable
+    ABI, you can continue to build a single wheel for multiple
+    non-free-threaded Python versions.
 
 
 Windows

Doc/howto/free-threading-python.rst

@@ -105,7 +105,12 @@ As of the 3.14 release, immortalization is limited to:
 
 * Code constants: numeric literals, string literals, and tuple literals
   composed of other constants.
-* Strings interned by :func:`sys.intern`.
+* All interned strings, including those interned by :func:`sys.intern`
+  and the names used in code objects (see
+  :ref:`below <ft-interned-immortal>`).
+
+Objects that are immortal in the default build, such as ``None``, small
+integers and static types, are also immortal in the free-threaded build.
 
 
 Frame objects
@@ -171,6 +176,8 @@ The free-threaded build will typically use more memory compared to the default
 build.  There are multiple reasons for this, mostly due to design decisions.
 
 
+.. _ft-interned-immortal:
+
 All interned strings are immortal
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -255,7 +262,8 @@ following types:
 
 * module objects
 * module top-level functions
-* class methods defined in the class scope
+* functions defined in a class scope (methods)
+* :func:`classmethod` and :func:`staticmethod` objects
 * descriptor objects
 * thread-local objects, created by :class:`threading.local`
 

Doc/library/threading.rst

@@ -97,16 +97,15 @@ GIL and performance considerations
 Unlike the :mod:`multiprocessing` module, which uses separate processes to
 bypass the :term:`global interpreter lock` (GIL), the threading module operates
 within a single process, meaning that all threads share the same memory space.
-However, the GIL limits the performance gains of threading when it comes to
-CPU-bound tasks, as only one thread can execute Python bytecode at a time.
-Despite this, threads remain a useful tool for achieving concurrency in many
-scenarios.
+However, in the default build the GIL limits the performance gains of threading
+when it comes to CPU-bound tasks, as only one thread can execute Python
+bytecode at a time.  Despite this, threads remain a useful tool for achieving
+concurrency in many scenarios.
 
 As of Python 3.13, :term:`free-threaded <free threading>` builds
-can disable the GIL, enabling true parallel execution of threads, but this
-feature is not available by default (see :pep:`703`).
-
-.. TODO: At some point this feature will become available by default.
+can disable the GIL, enabling true parallel execution of threads.  These
+builds are separate from the default build and must be installed or built
+explicitly (see :pep:`703` and :ref:`freethreading-python-howto`).
 
 Reference
 ---------