diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index d8d75ca6f2ec96..f33af51d1b9acb 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -362,8 +362,8 @@ class provides a featureful interface. What kinds of global value mutation are thread-safe? ---------------------------------------------------- -A :term:`global interpreter lock` (GIL) is used internally to ensure that only one -thread runs in the Python VM at a time. In general, Python offers to switch +In the default build of CPython, a :term:`global interpreter lock` (GIL) is +used internally to ensure that only one thread runs in the Python VM at a time. In general, Python offers to switch among threads only between bytecode instructions; how frequently it switches can be set via :func:`sys.setswitchinterval`. Each bytecode instruction and therefore all the C implementation code reached from each instruction is @@ -401,6 +401,17 @@ Operations that replace other objects may invoke those other objects' affect things. This is especially true for the mass updates to dictionaries and lists. When in doubt, use a mutex! +.. note:: + + The above relies on the GIL. In the :term:`free-threaded ` + build, where the GIL is disabled, threads can run bytecode in parallel and + a bytecode instruction is not atomic in general. Built-in types such as + :class:`list`, :class:`dict` and :class:`set` use internal locks so that + individual operations on them still behave atomically, but compound + operations such as ``D[x] = D[x] + 1`` remain unsafe. See + :ref:`threadsafety` for the guarantees provided for built-in types and + :ref:`freethreading-python-howto` for more information. + Can't we get rid of the Global Interpreter Lock? ------------------------------------------------ @@ -410,14 +421,12 @@ deployment on high-end multiprocessor server machines, because a multi-threaded Python program effectively only uses one CPU, due to the insistence that (almost) all Python code can only run while the GIL is held. -With the approval of :pep:`703` work is now underway to remove the GIL from the -CPython implementation of Python. Initially it will be implemented as an -optional compiler flag when building the interpreter, and so separate -builds will be available with and without the GIL. Long-term, the hope is -to settle on a single build, once the performance implications of removing the -GIL are fully understood. Python 3.13 is likely to be the first release -containing this work, although it may not be completely functional in this -release. +CPython has a supported :term:`free-threaded ` build in which +the GIL is disabled (:pep:`703`). It is built with the +:option:`--disable-gil` configure option, so separate builds are available with +and without the GIL. See :ref:`freethreading-python-howto` for details. +Long-term, the hope is to settle on a single build, once the performance +implications of removing the GIL are fully understood. The current work to remove the GIL is based on a `fork of Python 3.9 with the GIL removed `_ diff --git a/Doc/howto/free-threading-extensions.rst b/Doc/howto/free-threading-extensions.rst index ad0578df0a2702..e7b1b509a93424 100644 --- a/Doc/howto/free-threading-extensions.rst +++ b/Doc/howto/free-threading-extensions.rst @@ -425,17 +425,24 @@ The wheels, shared libraries, and binaries are indicated by a ``t`` suffix. Limited C API and Stable ABI ............................ -The free-threaded build does not currently support the +Starting with Python 3.15, the free-threaded build supports the +:ref:`Limited C API ` and a variant of the stable ABI called +``abi3t``. See :ref:`abi3t-migration-howto` for how to target it, and +:ref:`stable-abi` for how ``abi3t`` relates to ``abi3``. + +The free-threaded builds of Python 3.14 and older do not support the :ref:`Limited C API ` or the stable ABI. If you use `setuptools `_ to build -your extension and currently set ``py_limited_api=True`` you can use +your extension for these versions and currently set ``py_limited_api=True``, +you can use ``py_limited_api=not sysconfig.get_config_var("Py_GIL_DISABLED")`` to opt out of the limited API when building with the free-threaded build. .. note:: - You will need to build separate wheels specifically for the free-threaded - build. If you currently use the stable ABI, you can continue to build a - single wheel for multiple non-free-threaded Python versions. + Unless you target ``abi3t``, you will need to build separate wheels + specifically for the free-threaded build. If you use the ``abi3`` stable + ABI, you can continue to build a single wheel for multiple + non-free-threaded Python versions. Windows diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index 676fffac9d33ee..9efebf3ced47ab 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -105,7 +105,12 @@ As of the 3.14 release, immortalization is limited to: * Code constants: numeric literals, string literals, and tuple literals composed of other constants. -* Strings interned by :func:`sys.intern`. +* All interned strings, including those interned by :func:`sys.intern` + and the names used in code objects (see + :ref:`below `). + +Objects that are immortal in the default build, such as ``None``, small +integers and static types, are also immortal in the free-threaded build. Frame objects @@ -171,6 +176,8 @@ The free-threaded build will typically use more memory compared to the default build. There are multiple reasons for this, mostly due to design decisions. +.. _ft-interned-immortal: + All interned strings are immortal ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -255,7 +262,8 @@ following types: * module objects * module top-level functions -* class methods defined in the class scope +* functions defined in a class scope (methods) +* :func:`classmethod` and :func:`staticmethod` objects * descriptor objects * thread-local objects, created by :class:`threading.local` diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 5d9a7b6314b166..8f9bf04d6afb54 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -97,16 +97,15 @@ GIL and performance considerations Unlike the :mod:`multiprocessing` module, which uses separate processes to bypass the :term:`global interpreter lock` (GIL), the threading module operates within a single process, meaning that all threads share the same memory space. -However, the GIL limits the performance gains of threading when it comes to -CPU-bound tasks, as only one thread can execute Python bytecode at a time. -Despite this, threads remain a useful tool for achieving concurrency in many -scenarios. +However, in the default build the GIL limits the performance gains of threading +when it comes to CPU-bound tasks, as only one thread can execute Python +bytecode at a time. Despite this, threads remain a useful tool for achieving +concurrency in many scenarios. As of Python 3.13, :term:`free-threaded ` builds -can disable the GIL, enabling true parallel execution of threads, but this -feature is not available by default (see :pep:`703`). - -.. TODO: At some point this feature will become available by default. +can disable the GIL, enabling true parallel execution of threads. These +builds are separate from the default build and must be installed or built +explicitly (see :pep:`703` and :ref:`freethreading-python-howto`). Reference ---------