-
-
Notifications
You must be signed in to change notification settings - Fork 30k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
gh-124370: Add "howto" for free-threaded Python #124371
base: main
Are you sure you want to change the base?
Changes from all commits
5b4a8aa
0252cf5
df1489e
5658fa8
ae0f637
1554fb9
3b173e0
91ec1ca
6078cfd
e02ed00
526737e
f24bdb7
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,148 @@ | ||
.. _freethreading-python-howto: | ||
|
||
********************************************** | ||
Python experimental support for free threading | ||
********************************************** | ||
|
||
Starting with the 3.13 release, CPython has experimental support for a build of | ||
Python called :term:`free threading` where the :term:`global interpreter lock` | ||
(GIL) is disabled. Free-threaded execution allows for full utilization of the | ||
available processing power by running threads in parallel on available CPU cores. | ||
While not all software will benefit from this automatically, programs | ||
designed with threading in mind will run faster on multi-core hardware. | ||
|
||
**The free-threaded mode is experimental** and work is ongoing to improve it: | ||
expect some bugs and a substantial single-threaded performance hit. | ||
|
||
This document describes the implications of free threading | ||
for Python code. See :ref:`freethreading-extensions-howto` for information on | ||
how to write C extensions that support the free-threaded build. | ||
|
||
.. seealso:: | ||
|
||
:pep:`703` – Making the Global Interpreter Lock Optional in CPython for an | ||
overall description of free-threaded Python. | ||
|
||
|
||
Installation | ||
============ | ||
|
||
Starting with Python 3.13, the official macOS and Windows installers | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Linux ? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We don't provide Linux installers. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Right, but we could mention here that people building their own CPython such as on Linux need to use There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Mostly I want to direct people to https://py-free-threading.github.io/installing_cpython/. That's going to be a lot more comprehensive. There are a lot of ways people install Python! I can make that part of the body of the text instead of a "see also" section |
||
optionally support installing free-threaded Python binaries. The installers | ||
are available at https://www.python.org/downloads/. | ||
|
||
For information on other platforms, see the `Installing a Free-Threaded Python | ||
<https://py-free-threading.github.io/installing_cpython/>`_, a | ||
community-maintained installation guide for installing free-threaded Python. | ||
|
||
When building CPython from source, the :option:`--disable-gil` configure option | ||
should be used to build a free-threaded Python interpreter. | ||
|
||
|
||
Identifying free-threaded Python | ||
================================ | ||
|
||
To check if the current interpreter supports free-threading, :option:`python -VV <-V>` | ||
and :attr:`sys.version` contain "experimental free-threading build". | ||
The new :func:`sys._is_gil_enabled` function can be used to check whether | ||
the GIL is actually disabled in the running process. | ||
|
||
The ``sysconfig.get_config_var("Py_GIL_DISABLED")`` configuration variable can | ||
be used to determine whether the build supports free threading. If the variable | ||
is set to ``1``, then the build supports free threading. This is the recommended | ||
mechanism for decisions related to the build configuration. | ||
|
||
|
||
The global interpreter lock in free-threaded Python | ||
=================================================== | ||
|
||
Free-threaded builds of CPython support optionally running with the GIL enabled | ||
at runtime using the environment variable :envvar:`PYTHON_GIL` or | ||
the command-line option :option:`-X gil`. | ||
|
||
The GIL may also automatically be enabled when importing a C-API extension | ||
module that is not explicitly marked as supporting free threading. See | ||
:c:macro:`Py_MOD_GIL_NOT_USED` for more details. | ||
|
||
|
||
Thread safety | ||
============= | ||
|
||
The free-threaded build of CPython aims to provide similar thread-safety | ||
behavior at the Python level to the default GIL-enabled build. Built-in | ||
types like :class:`dict`, :class:`list`, and :class:`set` use internal locks | ||
to protect against concurrent modifications in ways that behave similarly to | ||
the GIL. However, Python has not historically guaranteed specific behavior for | ||
concurrent modifications to these built-in types, so this should be treated | ||
as a description of the current implementation, not a guarantee of current or | ||
future behavior. | ||
|
||
.. note:: | ||
|
||
It's recommended to use the :class:`threading.Lock` or other synchronization | ||
willingc marked this conversation as resolved.
Show resolved
Hide resolved
|
||
primitives instead of relying on the internal locks of built-in types, when | ||
possible. | ||
|
||
|
||
Known limitations | ||
================= | ||
|
||
This section describes known limitations of the free-threaded CPython build. | ||
|
||
Immortalization | ||
--------------- | ||
|
||
The free-threaded build of the 3.13 release makes some objects :term:`immortal`. | ||
Immortal objects are not deallocated and have reference counts that are | ||
never modified. This is done to avoid reference count contention that would | ||
prevent efficient multi-threaded scaling. | ||
|
||
An object will be made immortal when a new thread is started for the first time | ||
after the main thread is running. The following objects are immortalized: | ||
|
||
* :ref:`function <user-defined-funcs>` objects declared at the module level | ||
* :ref:`method <instance-methods>` descriptors | ||
* :ref:`code <code-objects>` objects | ||
* :term:`module` objects and their dictionaries | ||
* :ref:`classes <classes>` (type objects) | ||
Comment on lines
+103
to
+107
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It's probably worth noting somewhere in here that these objects (and immortalization itself) are implementation details, and very much subject to change. |
||
|
||
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. | ||
|
||
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. | ||
|
||
|
||
Frame objects | ||
------------- | ||
|
||
It is not safe to access :ref:`frame <frame-objects>` objects from other | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can you elaborate on how it is not safe? What might happen? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Your program may crash. I'll add it to the guide. |
||
threads and doing so may cause your program to crash . This means that | ||
:func:`sys._current_frames` is generally not safe to use in a free-threaded | ||
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 | ||
--------- | ||
|
||
Sharing the same iterator object between multiple threads is generally not | ||
safe and threads may see duplicate or missing elements when iterating or crash | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is the possible crashing of the interpreter expected to be addressed in 3.14? As a consequence of iterators not being thread safe, some modules are not safe either (e g. |
||
the interpreter. | ||
|
||
|
||
Single-threaded performance | ||
--------------------------- | ||
|
||
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 | ||
40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is surprising: the lore around removing the GIL has always been that it was easy, the hard part was doing it without affecting single-threaded performance. This seems like a significant hit. I understand it's a work in progress, and performance will be improved, but maybe we could elaborate on that a bit here. |
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if we could add a quick snapshot of the overall plan: if everything works out, eventually free threading will be the only build, etc. Also, maybe a statement about how most programmer won't need to be concerned with this, we're doing a lot to keep everyday Python programs behaving the same, etc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would perhaps add a note in the seealso block that refers to the PEP and adds 1 or 2 highlights: