Skip to content

gh-124370: Add "howto" for free-threaded Python #124371

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.

Sign up for GitHub

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

Merged
nedbat merged 13 commits into from
Sep 25, 2024
Merged

gh-124370: Add "howto" for free-threaded Python #124371

Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
5b4a8aa
gh-124370: Add "howto" for free-threaded Python
colesbury Jun 21, 2024
0252cf5
Add missing new line
colesbury Sep 23, 2024
df1489e
Update Doc/howto/free-threading-python.rst
colesbury Sep 23, 2024
5658fa8
interned -> immortalized
colesbury Sep 23, 2024
ae0f637
Apply suggestions from code review
colesbury Sep 23, 2024
1554fb9
Update Doc/howto/free-threading-python.rst
colesbury Sep 24, 2024
3b173e0
Update docs
colesbury Sep 24, 2024
91ec1ca
Apply suggestions from code review
colesbury Sep 24, 2024
6078cfd
A few more updates
colesbury Sep 24, 2024
e02ed00
Additional comment on immortal objects
colesbury Sep 24, 2024
526737e
Mention specializing adaptive interpreter
colesbury Sep 24, 2024
f24bdb7
Remove trailing whitespace
colesbury Sep 24, 2024
a3ad6b3
Remove mention of C macro
colesbury Sep 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
A few more updates
  • Loading branch information
@colesbury
colesbury committed Sep 24, 2024
commit 6078cfd54e65c5b7a3c7fc08355194b524500754
71 changes: 43 additions & 28 deletions Doc/howto/free-threading-python.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,19 @@
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. 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.
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::

Expand All @@ -22,31 +31,40 @@ Starting with Python 3.13, the official macOS and Windows installers
optionally support installing free-threaded Python binaries. The installers
are available at https://www.python.org/downloads/.

.. seealso::
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.

`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
================================

The free-threaded build of CPython can optionally run with the global
interpreter lock enabled, such as when :envvar:`PYTHON_GIL` is set to ``1``,
or automatically when importing an extension module that requires the GIL.

The :func:`sys._is_gil_enabled` function will return ``False`` if the global
interpreter lock is currently disabled. This is the recommended mechanism for
decisions like whether to use multithreading or multiprocessing.
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.

@nedbat nedbat Sep 25, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this document is for Python programmers, I think we should avoid sending them off to look at C macros. As a Python programmer, my question now would be, "how can I tell if my C extensions support free threading or not?" Is there a way to know without examining the C source code?

@colesbury colesbury Sep 25, 2024

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can remove the link and mention of the C macro. There isn't a great answer for "how can I tell if my C extensions support free threading?"

@nedbat nedbat Sep 25, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those are good answers!



Thread safety
=============

Expand All @@ -56,8 +74,8 @@ 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.
as a description of the current implementation, not a guarantee of current or
future behavior.

.. note::

Expand All @@ -66,7 +84,6 @@ behavior.
possible.



Known limitations
=================

Expand All @@ -75,23 +92,21 @@ 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`
in order to avoid reference count contention that would prevent efficient
multi-threaded scaling. This means that these objects are never deallocated.
This is expected to be addressed in Python 3.14 with
`deferred reference counting <https://peps.python.org/pep-0703/#deferred-reference-counting>`_.
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:
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 +109 to +113

@ZeroIntensity ZeroIntensity Sep 23, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The 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.


The immortalization of these objects happens the first time a thread is started
after the main thread.


Additionally, numeric and string literals in the code as well as strings
returned by :func:`sys.intern` are also immortalized. This behavior is
Expand Down