From c07f6d648078c3cb658506a422ebd450a68eacac Mon Sep 17 00:00:00 2001 From: Hernani Samuel Diniz Date: Fri, 23 Jan 2026 09:33:52 -0300 Subject: [PATCH 1/6] gh-144161: Clarify additional immortalization in free-threaded build Clarify that the objects listed in the free-threading HOWTO are additional immortalizations specific to the free-threaded build. This addresses the inconsistency with sys.intern() documentation, which describes the default (mortal) behavior. --- 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 380c2be04957d5..2442a6725d62fc 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -99,12 +99,12 @@ This section describes known limitations of the free-threaded CPython build. Immortalization --------------- -In the free-threaded build, some objects are :term:`immortal`. +The free-threaded build introduces additional :term:`immortal` objects. Immortal objects are not deallocated and have reference counts that are never modified. This is done to avoid reference count contention that would prevent efficient multi-threaded scaling. -As of the 3.14 release, immortalization is limited to: +As of the 3.14 release, this additional immortalization is limited to: * Code constants: numeric literals, string literals, and tuple literals composed of other constants. From 23817770b3fea14ee10c7959f6a7693b80b1cd27 Mon Sep 17 00:00:00 2001 From: Hernani Samuel Diniz Date: Sat, 24 Jan 2026 11:26:21 -0300 Subject: [PATCH 2/6] Add notes to sys.intern and PyUnicode_InternInPlace about immortal strings --- Doc/c-api/unicode.rst | 2 ++ Doc/library/sys.rst | 3 +++ 2 files changed, 5 insertions(+) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index d2b6643c700e88..d481d1c733dc3a 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1753,6 +1753,8 @@ They all return ``NULL`` or ``-1`` if an exception occurs. Note that interned strings are not “immortal”. You must keep a reference to the result to benefit from interning. + .. note:: + In the free-threaded build, all interned strings are :term:`immortal`. .. c:function:: PyObject* PyUnicode_InternFromString(const char *str) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index f977f1389b61a5..1a5029070f6d82 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1325,6 +1325,9 @@ always available. Unless explicitly noted otherwise, all variables are read-only Interned strings are not :term:`immortal`; you must keep a reference to the return value of :func:`intern` around to benefit from it. + .. note:: + + In the free-threaded build, all interned strings are :term:`immortal`. .. function:: _is_gil_enabled() From 60877e61dd69e482d2c5be100371b58c76bd2cd3 Mon Sep 17 00:00:00 2001 From: Hernani Samuel Diniz Date: Sat, 24 Jan 2026 14:03:54 -0300 Subject: [PATCH 3/6] Address review comments: emphasize 'are' and rephrase to avoid duplicate 'Note' --- Doc/c-api/unicode.rst | 4 ++-- Doc/library/sys.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index d481d1c733dc3a..9a7bfbac83ec53 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1750,11 +1750,11 @@ They all return ``NULL`` or ``-1`` if an exception occurs. :c:expr:`PyUnicode_CheckExact(*p_unicode)` must be true. If it is not, then -- as with any other error -- the argument is left unchanged. - Note that interned strings are not “immortal”. + Interned strings are not :term:`immortal`. You must keep a reference to the result to benefit from interning. .. note:: - In the free-threaded build, all interned strings are :term:`immortal`. + In the free-threaded build, all interned strings **are** :term:`immortal`. .. c:function:: PyObject* PyUnicode_InternFromString(const char *str) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 1a5029070f6d82..abdb92f462588c 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1327,7 +1327,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only .. note:: - In the free-threaded build, all interned strings are :term:`immortal`. + In the free-threaded build, all interned strings **are** :term:`immortal`. .. function:: _is_gil_enabled() From 8615a75fe18bfd13ec882563befe4ba9a73805f8 Mon Sep 17 00:00:00 2001 From: Hernani Samuel Diniz Date: Sat, 24 Jan 2026 15:45:00 -0300 Subject: [PATCH 4/6] Docs: address review feedback on interned string immortality --- Doc/c-api/unicode.rst | 5 +++-- Doc/howto/free-threading-python.rst | 2 +- Doc/library/sys.rst | 4 ++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 9a7bfbac83ec53..0c4ce2b56cd9c6 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1750,11 +1750,12 @@ They all return ``NULL`` or ``-1`` if an exception occurs. :c:expr:`PyUnicode_CheckExact(*p_unicode)` must be true. If it is not, then -- as with any other error -- the argument is left unchanged. - Interned strings are not :term:`immortal`. + Strings interned by this function are not :term:`immortal`. You must keep a reference to the result to benefit from interning. .. note:: - In the free-threaded build, all interned strings **are** :term:`immortal`. + On the :term:`free threaded` build, all interned strings are :term:`immortal`. + This may change in the future. .. c:function:: PyObject* PyUnicode_InternFromString(const char *str) diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst index 2442a6725d62fc..e7fd5247cfd98d 100644 --- a/Doc/howto/free-threading-python.rst +++ b/Doc/howto/free-threading-python.rst @@ -99,7 +99,7 @@ This section describes known limitations of the free-threaded CPython build. Immortalization --------------- -The free-threaded build introduces additional :term:`immortal` objects. +On the free-threaded build, more objects are made immortal. Immortal objects are not deallocated and have reference counts that are never modified. This is done to avoid reference count contention that would prevent efficient multi-threaded scaling. diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index abdb92f462588c..74c7a5ec822b99 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1326,8 +1326,8 @@ always available. Unless explicitly noted otherwise, all variables are read-only return value of :func:`intern` around to benefit from it. .. note:: - - In the free-threaded build, all interned strings **are** :term:`immortal`. + On the :term:`free threaded` build, all interned strings are :term:`immortal`. + This may change in the future. .. function:: _is_gil_enabled() From bd1935f8cd63ee6d0747b134f26980308ecf61a8 Mon Sep 17 00:00:00 2001 From: Hernani Samuel Diniz Date: Sat, 24 Jan 2026 16:02:05 -0300 Subject: [PATCH 5/6] gh-144161: fix glossary term 'free-threaded' --- Doc/c-api/unicode.rst | 2 +- Doc/library/sys.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 0c4ce2b56cd9c6..991c43f9a37796 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1754,7 +1754,7 @@ They all return ``NULL`` or ``-1`` if an exception occurs. You must keep a reference to the result to benefit from interning. .. note:: - On the :term:`free threaded` build, all interned strings are :term:`immortal`. + On the :term:`free-threaded` build, all interned strings are :term:`immortal`. This may change in the future. .. c:function:: PyObject* PyUnicode_InternFromString(const char *str) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 74c7a5ec822b99..04ee63b0f3e66c 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1326,7 +1326,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only return value of :func:`intern` around to benefit from it. .. note:: - On the :term:`free threaded` build, all interned strings are :term:`immortal`. + On the :term:`free-threaded` build, all interned strings are :term:`immortal`. This may change in the future. .. function:: _is_gil_enabled() From d261c91a763e15e0ac626d67322e3d2f24bf4890 Mon Sep 17 00:00:00 2001 From: Hernani Samuel Diniz Date: Sat, 24 Jan 2026 16:22:06 -0300 Subject: [PATCH 6/6] Remove :term: reference from 'free-threaded' (not in glossary) --- Doc/c-api/unicode.rst | 2 +- Doc/library/sys.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 991c43f9a37796..307e6f73d03eb8 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -1754,7 +1754,7 @@ They all return ``NULL`` or ``-1`` if an exception occurs. You must keep a reference to the result to benefit from interning. .. note:: - On the :term:`free-threaded` build, all interned strings are :term:`immortal`. + On the free-threaded build, all interned strings are :term:`immortal`. This may change in the future. .. c:function:: PyObject* PyUnicode_InternFromString(const char *str) diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 04ee63b0f3e66c..3644ce1479578c 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1326,7 +1326,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only return value of :func:`intern` around to benefit from it. .. note:: - On the :term:`free-threaded` build, all interned strings are :term:`immortal`. + On the free-threaded build, all interned strings are :term:`immortal`. This may change in the future. .. function:: _is_gil_enabled()