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/2] 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/2] 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()