greg/cpython
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Lysandros Nikolaou
2025-11-06 11:20:02 +01:00
committed by GitHub
parent 13360efd38
commit 86ab7bb87a
2 changed files with 18 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
Doc/howto/free-threading-extensions.rst
View File

@@ -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

21
Doc/howto/free-threading-python.rst
View File

@@ -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