From b5298d8acfb982a2ec723e3ea5ae15ee1ea6be78 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:00:59 +0900 Subject: [PATCH 01/13] gh-119132: Remove "experimental" tag from the CPython free-threading build --- Lib/platform.py | 2 +- Python/getversion.c | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Lib/platform.py b/Lib/platform.py index 077db81264a57c..e7f180fc5ac3a3 100644 --- a/Lib/platform.py +++ b/Lib/platform.py @@ -1144,7 +1144,7 @@ def _sys_version(sys_version=None): # CPython cpython_sys_version_parser = re.compile( r'([\w.+]+)\s*' # "version" - r'(?:experimental free-threading build\s+)?' # "free-threading-build" + r'(?:free-threading build\s+)?' # "free-threading-build" r'\(#?([^,]+)' # "(#buildno" r'(?:,\s*([\w ]*)' # ", builddate" r'(?:,\s*([\w :]*))?)?\)\s*' # ", buildtime)" diff --git a/Python/getversion.c b/Python/getversion.c index 226b2f999a6bfd..8d8bc6ea70048c 100644 --- a/Python/getversion.c +++ b/Python/getversion.c @@ -15,7 +15,7 @@ void _Py_InitVersion(void) } initialized = 1; #ifdef Py_GIL_DISABLED - const char *buildinfo_format = "%.80s experimental free-threading build (%.80s) %.80s"; + const char *buildinfo_format = "%.80s free-threading build (%.80s) %.80s"; #else const char *buildinfo_format = "%.80s (%.80s) %.80s"; #endif From 1f4ec9d31d2028015e421bce63a14d5c06d87035 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:17:49 +0900 Subject: [PATCH 02/13] Address code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/howto/free-threading-python.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index c33cef2c8e935b..b8dd1b880e0699 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -1,18 +1,18 @@ .. _freethreading-python-howto: ********************************************** -Python experimental support for free threading +Python support for free threading ********************************************** -Starting with the 3.13 release, CPython has experimental support for a build of +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 experimental** and work is ongoing to improve it: -expect some bugs and a substantial single-threaded performance hit. +The free-threaded mode is working and continues to be improved: +expect some bugs and a substantial performance hit in single-threaded workloads. This document describes the implications of free threading for Python code. See :ref:`freethreading-extensions-howto` for information on @@ -43,7 +43,7 @@ Identifying free-threaded Python ================================ To check if the current interpreter supports free-threading, :option:`python -VV <-V>` -and :data:`sys.version` contain "experimental free-threading build". +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. From e668b84a51f8efde6b74654d278d396298fe0689 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:20:31 +0900 Subject: [PATCH 03/13] Add NEWS.d --- .../next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst diff --git a/Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst b/Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst new file mode 100644 index 00000000000000..08c72e4f2d1ff2 --- /dev/null +++ b/Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst @@ -0,0 +1 @@ +Remove "experimental" tag from the CPython free-threading. From 42c868f6dc1c27db80f592ac7281c4a50878c1cf Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:27:09 +0900 Subject: [PATCH 04/13] Regen configure.ac --- configure | 4 ++-- configure.ac | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/configure b/configure index 6c4923e82a886d..2b1482d9264d24 100755 --- a/configure +++ b/configure @@ -1826,8 +1826,8 @@ Optional Features: no) --enable-profiling enable C-level code profiling with gprof (default is no) - --disable-gil enable experimental support for running without the - GIL (default is no) + --disable-gil enable support for running without the GIL (default + is no) --enable-pystats enable internal statistics gathering (default is no) --enable-optimizations enable expensive, stable optimizations (PGO, etc.) (default is no) diff --git a/configure.ac b/configure.ac index 4f935aacef1665..7dbb332f1d30a7 100644 --- a/configure.ac +++ b/configure.ac @@ -1716,7 +1716,7 @@ ABI_THREAD="" # --disable-gil AC_MSG_CHECKING([for --disable-gil]) AC_ARG_ENABLE([gil], - [AS_HELP_STRING([--disable-gil], [enable experimental support for running without the GIL (default is no)])], + [AS_HELP_STRING([--disable-gil], [enable support for running without the GIL (default is no)])], [AS_VAR_IF([enable_gil], [yes], [disable_gil=no], [disable_gil=yes])], [disable_gil=no] ) AC_MSG_RESULT([$disable_gil]) From e78c2ef76708a9bf10983ae702d67cf6d1baac53 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:28:32 +0900 Subject: [PATCH 05/13] Update doc --- Doc/using/configure.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 0b7eaf35a1e689..36ca26d70a9d87 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -290,8 +290,7 @@ General Options .. option:: --disable-gil - Enables **experimental** support for running Python without the - :term:`global interpreter lock` (GIL): free threading build. + Enables support for running Python without the :term:`global interpreter lock` (GIL): free threading build. Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to :data:`sys.abiflags`. From 0d9a5dda01b338522ed342c1ae802645a151e287 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:29:14 +0900 Subject: [PATCH 06/13] Update --- PCbuild/build.bat | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PCbuild/build.bat b/PCbuild/build.bat index 2f358991e484ce..602357048867d6 100644 --- a/PCbuild/build.bat +++ b/PCbuild/build.bat @@ -33,7 +33,7 @@ echo. -k Attempt to kill any running Pythons before building (usually done echo. automatically by the pythoncore project) echo. --pgo Build with Profile-Guided Optimization. This flag echo. overrides -c and -d -echo. --disable-gil Enable experimental support for running without the GIL. +echo. --disable-gil Enable support for running without the GIL. echo. --test-marker Enable the test marker within the build. echo. --regen Regenerate all opcodes, grammar and tokens. echo. --experimental-jit Enable the experimental just-in-time compiler. From 6552d56b2d78941e054a45ab679e5acae48a626d Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:31:00 +0900 Subject: [PATCH 07/13] Update --- Doc/howto/free-threading-extensions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/free-threading-extensions.rst b/Doc/howto/free-threading-extensions.rst index 175bb5dc831848..02b45879ccfaca 100644 --- a/Doc/howto/free-threading-extensions.rst +++ b/Doc/howto/free-threading-extensions.rst @@ -6,8 +6,8 @@ C API Extension 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 +Starting with the 3.13 release, CPython has support for running with +the :term:`global interpreter lock` (GIL) disabled in a configuration called :term:`free threading`. This document describes how to adapt C API extensions to support free threading. From 8ba1ab3ac7866d1e338a1ba907f7838a0d19c67f Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:37:48 +0900 Subject: [PATCH 08/13] Update --- Doc/library/threading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 7edcdcabdce1df..52fefd590daf18 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -102,7 +102,7 @@ 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, experimental :term:`free-threaded ` builds +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`). From 216b8f309c8b4c4f6fab3c79ca957a6926afa2bb Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:42:14 +0900 Subject: [PATCH 09/13] Update Doc/howto/free-threading-python.rst Co-authored-by: Peter Bierma --- Doc/howto/free-threading-python.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index b8dd1b880e0699..17b332ca144209 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -11,7 +11,7 @@ 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: +The free-threaded mode is working and continues to be improved, but expect some bugs and a substantial performance hit in single-threaded workloads. This document describes the implications of free threading From a53448c855f2c95e656379d67ffb28cadf95ce59 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:44:11 +0900 Subject: [PATCH 10/13] Update ctypes.rst --- Doc/library/ctypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 2ee4450698a107..a9498ecf8692db 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -882,7 +882,7 @@ invalid non-\ ``NULL`` pointers would crash Python):: Thread safety without the GIL ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In Python 3.13, the :term:`GIL` may be disabled on :term:`experimental free threaded ` builds. +From Python 3.13, the :term:`GIL` can be disabled on :term:`free threaded ` builds. In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects: .. code-block:: pycon From 75308de12479a776b8c93663098e805e43103efb Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 07:44:51 +0900 Subject: [PATCH 11/13] Update --- Doc/howto/free-threading-python.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index 17b332ca144209..d89d68566bad95 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -1,8 +1,8 @@ .. _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` From b9df331aa1587dc5b7feebeb5457be8506fc17c5 Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 22:08:08 +0900 Subject: [PATCH 12/13] Update Doc/howto/free-threading-python.rst Co-authored-by: T. Wouters --- Doc/howto/free-threading-python.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index d89d68566bad95..24069617c47ae1 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -12,7 +12,10 @@ 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 -expect some bugs and a substantial performance hit in single-threaded workloads. +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 From 8655c6bb941077bfd6491fddc85b164a29ffcb0f Mon Sep 17 00:00:00 2001 From: Donghee Na Date: Mon, 16 Jun 2025 22:47:51 +0900 Subject: [PATCH 13/13] Apply suggestions from code review Co-authored-by: T. Wouters Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/library/ctypes.rst | 2 +- Doc/using/configure.rst | 3 ++- .../next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index a9498ecf8692db..e00fe9c8145f12 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -882,7 +882,7 @@ invalid non-\ ``NULL`` pointers would crash Python):: Thread safety without the GIL ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -From Python 3.13, the :term:`GIL` can be disabled on :term:`free threaded ` builds. +From Python 3.13 onward, the :term:`GIL` can be disabled on :term:`free threaded ` builds. In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects: .. code-block:: pycon diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 36ca26d70a9d87..df81a330549147 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -290,7 +290,8 @@ General Options .. option:: --disable-gil - Enables support for running Python without the :term:`global interpreter lock` (GIL): free threading build. + Enables support for running Python without the :term:`global interpreter + lock` (GIL): free threading build. Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to :data:`sys.abiflags`. diff --git a/Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst b/Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst index 08c72e4f2d1ff2..3eb0805b9ce1be 100644 --- a/Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst +++ b/Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst @@ -1 +1 @@ -Remove "experimental" tag from the CPython free-threading. +Remove "experimental" tag from the CPython free-threading build.