From 941011374ac21c90c7477ae42d2c193dfe500668 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 16 Jun 2025 16:58:14 +0200 Subject: [PATCH] [3.14] gh-119132: Remove "experimental" tag from the CPython free-threading. (gh-135550) (gh-135565) --------- (cherry picked from commit f0799795994bfd9ab0740c4d70ac54270991ba47) Co-authored-by: Donghee Na Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Peter Bierma Co-authored-by: T. Wouters --- Doc/howto/free-threading-extensions.rst | 4 ++-- Doc/howto/free-threading-python.rst | 17 ++++++++++------- Doc/library/ctypes.rst | 2 +- Doc/library/threading.rst | 2 +- Doc/using/configure.rst | 4 ++-- Lib/platform.py | 2 +- ...25-06-16-07-20-28.gh-issue-119132.fcI8s7.rst | 1 + PCbuild/build.bat | 2 +- Python/getversion.c | 2 +- configure | 4 ++-- configure.ac | 2 +- 11 files changed, 23 insertions(+), 19 deletions(-) create mode 100644 Misc/NEWS.d/next/Build/2025-06-16-07-20-28.gh-issue-119132.fcI8s7.rst diff --git a/Doc/howto/free-threading-extensions.rst b/Doc/howto/free-threading-extensions.rst index 175bb5dc8318..02b45879ccfa 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. diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index c33cef2c8e93..24069617c47a 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -1,18 +1,21 @@ .. _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, 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 @@ -43,7 +46,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. diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 2ee4450698a1..e00fe9c8145f 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 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/library/threading.rst b/Doc/library/threading.rst index 7edcdcabdce1..52fefd590daf 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`). diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 0b7eaf35a1e6..df81a3305491 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -290,8 +290,8 @@ 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`. diff --git a/Lib/platform.py b/Lib/platform.py index 55e211212d42..7dd64de6025d 100644 --- a/Lib/platform.py +++ b/Lib/platform.py @@ -1198,7 +1198,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/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 000000000000..3eb0805b9ce1 --- /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 build. diff --git a/PCbuild/build.bat b/PCbuild/build.bat index 2f358991e484..602357048867 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. diff --git a/Python/getversion.c b/Python/getversion.c index 226b2f999a6b..8d8bc6ea7004 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 diff --git a/configure b/configure index 015f2e7cac10..882e0409d604 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 fb48f39d3360..c26e5c7fd1dd 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]) -- 2.47.3