/
githubmirror
/
cpython
Обзор
Документация
Войти
/
githubmirror
/
cpython
Код
Запросы
0
Пакеты
0
Релизы
0
Аналитика
Безопасность
v3.15.0a2
Doc/howto/free-threading-python.rst
190 строк
8 KB
Lysandros Nikolaou
gh-137232: Update free-threading HOWTOs with up-to-date info for 3.14 (#140817)
06 ноя 2025, 13:20
Не верифицирован
06 ноя 2025, 13:20
86ab7bb
Код
Авторство
О чём код?
.. _freethreading-python-howto: ********************************* Python support for free threading ********************************* Starting with the 3.13 release, CPython has 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 working and continues to be improved, but 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 free-threaded build, and will re-enable the :term:`GIL`. 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 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 :data:`sys.version` contain "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. A warning will be printed in this case. In addition to individual package documentation, the following websites track the status of popular packages support for free threading: * https://py-free-threading.github.io/tracking/ * https://hugovk.github.io/free-threaded-wheels/ 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 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) 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 ------------- It is not safe to access :ref:`frame <frame-objects>` objects from other 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 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. 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. 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 ================== This section describes CPython behavioural changes with the free-threaded build. Context variables ----------------- In the free-threaded build, the flag :data:`~sys.flags.thread_inherit_context` is set to true by default which causes threads created with :class:`threading.Thread` to start with a copy of the :class:`~contextvars.Context()` of the caller of :meth:`~threading.Thread.start`. In the default GIL-enabled build, the flag defaults to false so threads start with an empty :class:`~contextvars.Context()`. Warning filters --------------- In the free-threaded build, the flag :data:`~sys.flags.context_aware_warnings` is set to true by default. In the default GIL-enabled build, the flag defaults to false. If the flag is true then the :class:`warnings.catch_warnings` context manager uses a context variable for warning filters. If the flag is false then :class:`~warnings.catch_warnings` modifies the global filters list, which is not thread-safe. See the :mod:`warnings` module for more details.