diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst new file mode 100644 index 00000000000000..1912338b028bd9 --- /dev/null +++ b/Doc/howto/free-threading-python.rst @@ -0,0 +1,119 @@ +.. _freethreading-python-howto: + +********************************* +Python Support for Free Threading +********************************* + +Starting with the 3.13 release, CPython has experimental support for running +with the :term:`global interpreter lock` (GIL) disabled in a configuration +called :term:`free threading`. 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. + + +Installation +============ + +Starting with Python 3.13.0b2, the offical macOS and Windows installers +optionally support installing free-threaded Python binaries. The installers +are available at https://www.python.org/downloads/. + +.. seealso:: + + `Installing a Free-Threaded Python + `_: + A community-maintained installation guide for installing free-threaded + Python. + + +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 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. + +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. + + +Thread Safety +============= + +The free-threaded build of CPython aims to provide similar thread-safety +behavior at the Python level to the 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 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` +in order to avoid reference count contention that would prevent efficient +multi-threaded scaling. This means that these objects are never deallocated. +This expected to be addressed in the upcoming 3.14 release with +`deferred reference counting `_. + +The objects that are immortalized are: + +* :ref:`function ` objects declared at the module level +* :ref:`method ` descriptors +* :ref:`code ` objects +* :term:`module` objects and their dictionaries +* :ref:`classes ` (type objects) + +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 interned. This behavior is expected to +remainin the 3.14 free-threaded build. + + +Frame Objects +------------- + +It is not safe to access :ref:`frame ` objects from other +threads. This means that :func:`sys._current_frames` is generally not safe to +use in a free-threaded build. + +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 `_ suite. +Programs that spend most of the their time in C extensions or I/O will see +less of an impact. This overhead is expected to be reduced in the upcoming +3.14 release. \ No newline at end of file diff --git a/Doc/howto/index.rst b/Doc/howto/index.rst index a882f1747084fe..c09f92c9528ee1 100644 --- a/Doc/howto/index.rst +++ b/Doc/howto/index.rst @@ -32,6 +32,7 @@ Python Library Reference. isolating-extensions.rst timerfd.rst mro.rst + free-threading-python.rst free-threading-extensions.rst General: @@ -52,6 +53,7 @@ General: Advanced development: * :ref:`curses-howto` +* :ref:`freethreading-python-howto` * :ref:`freethreading-extensions-howto` * :ref:`isolating-extensions-howto` * :ref:`python_2.3_mro` diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 21aee0b6d0e3c5..7d40fea2a6979d 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -846,6 +846,7 @@ this case, the special read-only attribute :attr:`!__self__` is set to the objec denoted by *alist*. (The attribute has the same semantics as it does with :attr:`other instance methods `.) +.. _classes: Classes ^^^^^^^