From 58161c7c2880d43cc2896975925c2d0249ed4c16 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 29 Jan 2026 22:31:17 -0500 Subject: [PATCH 1/4] Add a "free-threaded build" term. --- Doc/glossary.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 68035c2dfb57d4..4a408a3ed86723 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -580,6 +580,13 @@ Glossary the :term:`global interpreter lock` which allows only one thread to execute Python bytecode at a time. See :pep:`703`. + free-threaded build + + A build of :term:`CPython` that supports :term:`free threading`, + configured using the :option:`--disable-gil` option before compilation. + + See :ref:`freethreading-python-howto`. + free variable Formally, as defined in the :ref:`language execution model `, a free variable is any variable used in a namespace which is not a local variable in that From c45a3efb5eaa05472c230a7857e88b99cdac0996 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 29 Jan 2026 22:38:20 -0500 Subject: [PATCH 2/4] Use the term in a bunch of places. --- Doc/c-api/object.rst | 6 +++--- Doc/c-api/refcounting.rst | 2 +- Doc/library/ctypes.rst | 2 +- Doc/library/io.rst | 2 +- Doc/library/site.rst | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 127b50ac479638..5a338f5344b0bf 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -711,10 +711,10 @@ Object Protocol :c:func:`PyUnstable_EnableTryIncRef` must have been called earlier on *obj* or this function may spuriously return ``0`` in the - :term:`free threading` build. + :term:`free-threaded build`. This function is logically equivalent to the following C code, except that - it behaves atomically in the :term:`free threading` build:: + it behaves atomically in the :term:`free-threaded build`:: if (Py_REFCNT(op) > 0) { Py_INCREF(op); @@ -791,7 +791,7 @@ Object Protocol On GIL-enabled builds, this function is equivalent to :c:expr:`Py_REFCNT(op) == 1`. - On a :term:`free threaded ` build, this checks if *op*'s + On a :term:`free-threaded build`, this checks if *op*'s :term:`reference count` is equal to one and additionally checks if *op* is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not** thread-safe on free threaded builds; prefer this function. diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst index 57a0728d4e9af4..08ea15c8952f69 100644 --- a/Doc/c-api/refcounting.rst +++ b/Doc/c-api/refcounting.rst @@ -25,7 +25,7 @@ of Python objects. .. note:: - On :term:`free threaded ` builds of Python, returning 1 + On :term:`free-threaded build`s of Python, returning 1 isn't sufficient to determine if it's safe to treat *o* as having no access by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced` for that instead. diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 6038af99009d02..d2f4da08327323 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -896,7 +896,7 @@ invalid non-\ ``NULL`` pointers would crash Python):: Thread safety without the GIL ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -From Python 3.13 onward, the :term:`GIL` can be disabled on :term:`free threaded ` builds. +From Python 3.13 onward, the :term:`GIL` can be disabled on the :term:`free-threaded build`. In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects: .. code-block:: pycon diff --git a/Doc/library/io.rst b/Doc/library/io.rst index dfebccb5a9cb91..d1a9132db81602 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -720,7 +720,7 @@ than raw I/O does. contains initial data. Methods may be used from multiple threads without external locking in - :term:`free threading` builds. + :term:`free-threaded builds `. :class:`BytesIO` provides or overrides these methods in addition to those from :class:`BufferedIOBase` and :class:`IOBase`: diff --git a/Doc/library/site.rst b/Doc/library/site.rst index d93e4dc7c75f1a..ca2ac3b0098c46 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -34,7 +34,7 @@ For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads are skipped. For the tail part, it uses the empty string and then :file:`lib/site-packages` (on Windows) or :file:`lib/python{X.Y[t]}/site-packages` (on Unix and macOS). (The -optional suffix "t" indicates the :term:`free threading` build, and is +optional suffix "t" indicates the :term:`free-threaded build`, and is appended if ``"t"`` is present in the :data:`sys.abiflags` constant.) For each of the distinct head-tail combinations, it sees if it refers to an existing From a5c6c980bf78221564b609173aa87e8c485bf3cc Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 29 Jan 2026 22:41:44 -0500 Subject: [PATCH 3/4] Fix a few other instances. --- Doc/c-api/object.rst | 2 +- Doc/glossary.rst | 6 +++--- Doc/using/configure.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 5a338f5344b0bf..992a4383f97241 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -794,7 +794,7 @@ Object Protocol On a :term:`free-threaded build`, this checks if *op*'s :term:`reference count` is equal to one and additionally checks if *op* is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not** - thread-safe on free threaded builds; prefer this function. + thread-safe on free-threaded builds; prefer this function. The caller must hold an :term:`attached thread state`, despite the fact that this function doesn't call into the Python interpreter. This function diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 4a408a3ed86723..3a1a9f51fab40b 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -160,9 +160,9 @@ Glossary On most builds of Python, having an attached thread state implies that the caller holds the :term:`GIL` for the current interpreter, so only one OS thread can have an attached thread state at a given moment. In - :term:`free-threaded ` builds of Python, threads can concurrently - hold an attached thread state, allowing for true parallelism of the bytecode - interpreter. + :term:`free-threaded builds ` of Python, threads can + concurrently hold an attached thread state, allowing for true parallelism of + the bytecode interpreter. attribute A value associated with an object which is usually referenced by name diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index af055d35290429..66400cc21bb476 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -421,7 +421,7 @@ General Options :no-typesetting: Enables support for running Python without the :term:`global interpreter - lock` (GIL): free threading build. + lock` (GIL): :term:`free-threading build`. Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to :data:`sys.abiflags`. From 4ee440f87c8838ec085a4ae695e3457053538d5e Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 29 Jan 2026 22:43:51 -0500 Subject: [PATCH 4/4] Fix Sphinx errors. --- Doc/c-api/refcounting.rst | 2 +- Doc/glossary.rst | 2 +- Doc/using/configure.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst index 08ea15c8952f69..4d56a92bf2af79 100644 --- a/Doc/c-api/refcounting.rst +++ b/Doc/c-api/refcounting.rst @@ -25,7 +25,7 @@ of Python objects. .. note:: - On :term:`free-threaded build`s of Python, returning 1 + On :term:`free-threaded builds ` of Python, returning 1 isn't sufficient to determine if it's safe to treat *o* as having no access by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced` for that instead. diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 3a1a9f51fab40b..7c41f5bc27b070 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -160,7 +160,7 @@ Glossary On most builds of Python, having an attached thread state implies that the caller holds the :term:`GIL` for the current interpreter, so only one OS thread can have an attached thread state at a given moment. In - :term:`free-threaded builds ` of Python, threads can + :term:`free-threaded builds ` of Python, threads can concurrently hold an attached thread state, allowing for true parallelism of the bytecode interpreter. diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 66400cc21bb476..747c92fcb4010f 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -421,7 +421,7 @@ General Options :no-typesetting: Enables support for running Python without the :term:`global interpreter - lock` (GIL): :term:`free-threading build`. + lock` (GIL): :term:`free-threaded build`. Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to :data:`sys.abiflags`.