gh-137232: Update free-threading HOWTOs with up-to-date info for 3.14 (#140817)

diff --git a/Doc/howto/free-threading-extensions.rst b/Doc/howto/free-threading-extensions.rst
index 3776132c685414c672a29d3288e25475464a165b..5647ab2d87c79c351276b875f9bf88b66dece7d5 100644 (file)
--- a/Doc/howto/free-threading-extensions.rst
+++ b/Doc/howto/free-threading-extensions.rst
@@ -203,7 +203,7 @@ Memory Allocation APIs
 Python's memory management C API provides functions in three different
 :ref:`allocation domains <allocator-domains>`: "raw", "mem", and "object".
 For thread-safety, the free-threaded build requires that only Python objects
-are allocated using the object domain, and that all Python object are
+are allocated using the object domain, and that all Python objects are
 allocated using that domain.  This differs from the prior Python versions,
 where this was only a best practice and not a hard requirement.
 
@@ -344,12 +344,12 @@ This means you cannot rely on nested critical sections to lock multiple objects
 at once, as the inner critical section may suspend the outer ones. Instead, use
 :c:macro:`Py_BEGIN_CRITICAL_SECTION2` to lock two objects simultaneously.
 
-Note that the locks described above are only :c:type:`!PyMutex` based locks.
+Note that the locks described above are only :c:type:`PyMutex` based locks.
 The critical section implementation does not know about or affect other locking
 mechanisms that might be in use, like POSIX mutexes.  Also note that while
-blocking on any :c:type:`!PyMutex` causes the critical sections to be
+blocking on any :c:type:`PyMutex` causes the critical sections to be
 suspended, only the mutexes that are part of the critical sections are
-released.  If :c:type:`!PyMutex` is used without a critical section, it will
+released.  If :c:type:`PyMutex` is used without a critical section, it will
 not be released and therefore does not get the same deadlock avoidance.
 
 Important Considerations
@@ -397,7 +397,8 @@ The wheels, shared libraries, and binaries are indicated by a ``t`` suffix.
 * `pypa/manylinux <https://github.com/pypa/manylinux>`_ supports the
   free-threaded build, with the ``t`` suffix, such as ``python3.13t``.
 * `pypa/cibuildwheel <https://github.com/pypa/cibuildwheel>`_ supports the
-  free-threaded build if you set
+  free-threaded build on Python 3.13 and 3.14. On Python 3.14, free-threaded
+  wheels will be built by default. On Python 3.13, you will need to set
   `CIBW_ENABLE to cpython-freethreading <https://cibuildwheel.pypa.io/en/stable/options/#enable>`_.
 
 Limited C API and Stable ABI

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
index 24069617c47ae18e1bc0bcb029ce202c39a95773..e4df7a787a2b172af3fd0aee70cbc45bb2296cfe 100644 (file)
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -116,12 +116,14 @@ after the main thread is running.  The following objects are immortalized:
 * :ref:`classes <classes>` (type objects)
 
 Because immortal objects are never deallocated, applications that create many
-objects of these types may see increased memory usage.  This is expected to be
-addressed in the 3.14 release.
+objects of these types may see increased memory usage under Python 3.13.  This
+has been addressed in the 3.14 release, where the aforementioned objects use
+deferred reference counting to avoid reference count contention.
 
 Additionally, numeric and string literals in the code as well as strings
-returned by :func:`sys.intern` are also immortalized.  This behavior is
-expected to remain in the 3.14 free-threaded build.
+returned by :func:`sys.intern` are also immortalized in the 3.13 release.  This
+behavior is part of the 3.14 release as well and it is expected to remain in
+future free-threaded builds.
 
 
 Frame objects
@@ -150,11 +152,12 @@ compared to the default GIL-enabled build.  In 3.13, this overhead is about
 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
 Programs that spend most of their time in C extensions or I/O will see
 less of an impact.  The largest impact is because the specializing adaptive
-interpreter (:pep:`659`) is disabled in the free-threaded build.  We expect
-to re-enable it in a thread-safe way in the 3.14 release.  This overhead is
-expected to be reduced in upcoming Python release.   We are aiming for an
-overhead of 10% or less on the pyperformance suite compared to the default
-GIL-enabled build.
+interpreter (:pep:`659`) is disabled in the free-threaded build.
+
+The specializing adaptive interpreter has been re-enabled in a thread-safe way
+in the 3.14 release.  The performance penalty on single-threaded code in
+free-threaded mode is now roughly 5-10%, depending on the platform and C
+compiler used.
 
 
 Behavioral changes