Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-08 06:10:17 +00:00
Code Issues Projects Releases Packages Wiki Activity

[3.14] gh-140281: Update free threading Python HOWTO for 3.14 (gh-140566) (gh-142173)

Browse source 
(cherry picked from commit 2dc28eb8b0)

Co-authored-by: Krishna-web-hub <masterkiran27@gmail.com>
Co-authored-by: Sam Gross <colesbury@gmail.com>
This commit is contained in:
Miss Islington (bot) 2025-12-02 07:06:15 +01:00 • committed by GitHub
parent 15a25f44ee
commit b053c2abf0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 17 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

57
Doc/howto/free-threading-python.rst
View file

@ -11,9 +11,7 @@ available processing power by running threads in parallel on available CPU cores
While not all software will benefit from this automatically, programs While not all software will benefit from this automatically, programs
designed with threading in mind will run faster on multi-core hardware. designed with threading in mind will run faster on multi-core hardware.
The free-threaded mode is working and continues to be improved, but Some third-party packages, in particular ones
there is some additional overhead in single-threaded workloads compared
to the regular build. Additionally, third-party packages, in particular ones
with an :term:`extension module`, may not be ready for use in a with an :term:`extension module`, may not be ready for use in a
free-threaded build, and will re-enable the :term:`GIL`. free-threaded build, and will re-enable the :term:`GIL`.
@ -101,63 +99,42 @@ This section describes known limitations of the free-threaded CPython build.
Immortalization Immortalization
--------------- ---------------
The free-threaded build of the 3.13 release makes some objects :term:`immortal`. In the free-threaded build, some objects are :term:`immortal`.
Immortal objects are not deallocated and have reference counts that are Immortal objects are not deallocated and have reference counts that are
never modified. This is done to avoid reference count contention that would never modified. This is done to avoid reference count contention that would
prevent efficient multi-threaded scaling. prevent efficient multi-threaded scaling.
An object will be made immortal when a new thread is started for the first time As of the 3.14 release, immortalization is limited to:
after the main thread is running. The following objects are immortalized:
* :ref:`function <user-defined-funcs>` objects declared at the module level * Code constants: numeric literals, string literals, and tuple literals
* :ref:`method <instance-methods>` descriptors composed of other constants.
* :ref:`code <code-objects>` objects * Strings interned by :func:`sys.intern`.
* :term:`module` objects and their dictionaries
* :ref:`classes <classes>` (type objects)
Because immortal objects are never deallocated, applications that create many
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 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 Frame objects
------------- -------------
It is not safe to access :ref:`frame <frame-objects>` objects from other It is not safe to access :attr:`frame.f_locals` from a :ref:`frame <frame-objects>`
threads and doing so may cause your program to crash . This means that object if that frame is currently executing in another thread, and doing so may
:func:`sys._current_frames` is generally not safe to use in a free-threaded crash the interpreter.
build. Functions like :func:`inspect.currentframe` and :func:`sys._getframe`
are generally safe as long as the resulting frame object is not passed to
another thread.
Iterators Iterators
--------- ---------
Sharing the same iterator object between multiple threads is generally not It is generally not thread-safe to access the same iterator object from
safe and threads may see duplicate or missing elements when iterating or crash multiple threads concurrently, and threads may see duplicate or missing
the interpreter. elements.
Single-threaded performance Single-threaded performance
--------------------------- ---------------------------
The free-threaded build has additional overhead when executing Python code The free-threaded build has additional overhead when executing Python code
compared to the default GIL-enabled build. In 3.13, this overhead is about compared to the default GIL-enabled build. The amount of overhead depends
40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite. on the workload and hardware. On the pyperformance benchmark suite, the
Programs that spend most of their time in C extensions or I/O will see average overhead ranges from about 1% on macOS aarch64 to 8% on x86-64 Linux
less of an impact. The largest impact is because the specializing adaptive systems.
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 Behavioral changes