From 5b4a8aa6d48e76181edcae389a3ebb540a34ac2f Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Fri, 21 Jun 2024 17:45:31 -0400
Subject: [PATCH 01/13] gh-124370: Add "howto" for free-threaded Python

This is a guide aimed at people writing Python code, as oppposed to the
existing guide for C API extension authors.
---
 Doc/howto/free-threading-python.rst | 119 ++++++++++++++++++++++++++++
 Doc/howto/index.rst                 |   2 +
 Doc/reference/datamodel.rst         |   1 +
 3 files changed, 122 insertions(+)
 create mode 100644 Doc/howto/free-threading-python.rst

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
new file mode 100644
index 00000000000000..1912338b028bd9
--- /dev/null
+++ b/Doc/howto/free-threading-python.rst
@@ -0,0 +1,119 @@
+.. _freethreading-python-howto:
+
+*********************************
+Python 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
+called :term:`free threading`.  This document describes the implications of
+free threading for Python code.  See :ref:`freethreading-extensions-howto` for
+information on how to write C extensions that support the free-threaded build.
+
+
+Installation
+============
+
+Starting with Python 3.13.0b2, the offical macOS and Windows installers
+optionally support installing free-threaded Python binaries.  The installers
+are available at https://www.python.org/downloads/.
+
+.. seealso::
+
+   `Installing a Free-Threaded Python
+   <https://py-free-threading.github.io/installing_cpython/>`_:
+   A community-maintained installation guide for installing free-threaded
+   Python.
+
+
+Identifying Free-Threaded Python
+================================
+
+The free-threaded build of CPython can optionally run with the global
+interpreter lock enabled, such as when :envvar:`PYTHON_GIL` is set to ``1``,
+or when importing an extension module that requires the GIL.
+
+The :func:`sys._is_gil_enabled` function will return ``False`` if the global
+interpreter lock is currently disabled.  This is the recommended mechanism for
+decisions like whether to use multithreading or multiprocessing.
+
+The ``sysconfig.get_config_var("Py_GIL_DISABLED")`` configuration variable can
+be used to determine whether the build supports free threading.  If the variable
+is set to ``1``, then the build supports free threading.  This is the recommended
+mechanism for decisions related to the build configuration.
+
+
+Thread Safety
+=============
+
+The free-threaded build of CPython aims to provide similar thread-safety
+behavior at the Python level to the GIL-enabled build.  Built-in
+types like :class:`dict`, :class:`list`, and :class:`set` use internal locks
+to protect against concurrent modifications in ways that behave similarly to
+the GIL.  However, Python has not historically guaranteed specific behavior for
+concurrent modifications to these built-in types, so this should be treated
+as a description of the current implementation, not a guarantee of future
+behavior.
+
+.. note::
+
+   It's recommended to use the :class:`threading.Lock` or other synchronization
+   primitives instead of relying on the internal locks of built-in types, when
+   possible.
+
+
+
+Known Limitations
+=================
+
+This section describes known limitations of the free-threaded CPython build.
+
+Immortalization
+---------------
+
+The free-threaded build of the 3.13 release makes some objects :term:`immortal`
+in order to avoid reference count contention that would prevent efficient
+multi-threaded scaling.  This means that these objects are never deallocated.
+This expected to be addressed in the upcoming 3.14 release with
+`deferred reference counting <https://peps.python.org/pep-0703/#deferred-reference-counting>`_.
+
+The objects that are immortalized are:
+
+* :ref:`function <user-defined-funcs>` objects declared at the module level
+* :ref:`method <instance-methods>` descriptors
+* :ref:`code <code-objects>` objects
+* :term:`module` objects and their dictionaries
+* :ref:`classes <classes>` (type objects)
+
+The immortalization of these objects happens the first time a thread is started
+after the main thread.
+
+Additionally, numeric and string literals in the code as well as strings
+returned by :func:`sys.intern` are also interned.  This behavior is expected to
+remainin the 3.14 free-threaded build.
+
+
+Frame Objects
+-------------
+
+It is not safe to access :ref:`frame <frame-objects>` objects from other
+threads.  This means that :func:`sys._current_frames` is generally not safe to
+use in a free-threaded build.
+
+Iterators
+---------
+
+Sharing the same iterator object between multiple threads is generally not
+safe and threads may see duplicate or missing elements when iterating or crash
+the interpreter.
+
+
+Single-Threaded Performance
+---------------------------
+
+The free-threaded build has additional overhead when executing Python code
+compared to the default GIL-enabled build.  In 3.13, this overhead is about
+40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
+Programs that spend most of the their time in C extensions or I/O will see
+less of an impact.  This overhead is expected to be reduced in the upcoming
+3.14 release.
\ No newline at end of file
diff --git a/Doc/howto/index.rst b/Doc/howto/index.rst
index a882f1747084fe..c09f92c9528ee1 100644
--- a/Doc/howto/index.rst
+++ b/Doc/howto/index.rst
@@ -32,6 +32,7 @@ Python Library Reference.
    isolating-extensions.rst
    timerfd.rst
    mro.rst
+   free-threading-python.rst
    free-threading-extensions.rst
 
 General:
@@ -52,6 +53,7 @@ General:
 Advanced development:
 
 * :ref:`curses-howto`
+* :ref:`freethreading-python-howto`
 * :ref:`freethreading-extensions-howto`
 * :ref:`isolating-extensions-howto`
 * :ref:`python_2.3_mro`
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 21aee0b6d0e3c5..7d40fea2a6979d 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -846,6 +846,7 @@ this case, the special read-only attribute :attr:`!__self__` is set to the objec
 denoted by *alist*. (The attribute has the same semantics as it does with
 :attr:`other instance methods <method.__self__>`.)
 
+.. _classes:
 
 Classes
 ^^^^^^^

From 0252cf597624fed541d2971634652b1cc0c74159 Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Mon, 23 Sep 2024 12:38:08 -0700
Subject: [PATCH 02/13] Add missing new line

---
 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 1912338b028bd9..95379e2c48c60a 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -116,4 +116,4 @@ compared to the default GIL-enabled build.  In 3.13, this overhead is about
 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
 Programs that spend most of the their time in C extensions or I/O will see
 less of an impact.  This overhead is expected to be reduced in the upcoming
-3.14 release.
\ No newline at end of file
+3.14 release.

From df1489e99f086e6a6ceaa7d0005e229ce56d81f4 Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Mon, 23 Sep 2024 13:42:55 -0700
Subject: [PATCH 03/13] Update Doc/howto/free-threading-python.rst

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 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 95379e2c48c60a..9aaf73910fb364 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -90,7 +90,7 @@ after the main thread.
 
 Additionally, numeric and string literals in the code as well as strings
 returned by :func:`sys.intern` are also interned.  This behavior is expected to
-remainin the 3.14 free-threaded build.
+remain in the 3.14 free-threaded build.
 
 
 Frame Objects

From 5658fa88ffb0d76eebfc7a3a1681d47b3595bbb9 Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Mon, 23 Sep 2024 13:43:36 -0700
Subject: [PATCH 04/13] interned -> immortalized

---
 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 9aaf73910fb364..7a26ccfee8857a 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -89,8 +89,8 @@ The immortalization of these objects happens the first time a thread is started
 after the main thread.
 
 Additionally, numeric and string literals in the code as well as strings
-returned by :func:`sys.intern` are also interned.  This behavior is expected to
-remain in the 3.14 free-threaded build.
+returned by :func:`sys.intern` are also immortalized.  This behavior is
+expected to remain in the 3.14 free-threaded build.
 
 
 Frame Objects

From ae0f6371e14acb1c09ec68f071222e8fb964e4cc Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Mon, 23 Sep 2024 16:20:07 -0700
Subject: [PATCH 05/13] Apply suggestions from code review

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
---
 Doc/howto/free-threading-python.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
index 7a26ccfee8857a..22ea04dcc8dbfc 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -1,7 +1,7 @@
 .. _freethreading-python-howto:
 
 *********************************
-Python Support for Free Threading
+Python support for free threading
 *********************************
 
 Starting with the 3.13 release, CPython has experimental support for running
@@ -14,7 +14,7 @@ information on how to write C extensions that support the free-threaded build.
 Installation
 ============
 
-Starting with Python 3.13.0b2, the offical macOS and Windows installers
+Starting with Python 3.13, the official macOS and Windows installers
 optionally support installing free-threaded Python binaries.  The installers
 are available at https://www.python.org/downloads/.
 
@@ -26,7 +26,7 @@ are available at https://www.python.org/downloads/.
    Python.
 
 
-Identifying Free-Threaded Python
+Identifying free-threaded Python
 ================================
 
 The free-threaded build of CPython can optionally run with the global
@@ -43,7 +43,7 @@ is set to ``1``, then the build supports free threading.  This is the recommende
 mechanism for decisions related to the build configuration.
 
 
-Thread Safety
+Thread safety
 =============
 
 The free-threaded build of CPython aims to provide similar thread-safety
@@ -63,7 +63,7 @@ behavior.
 
 
 
-Known Limitations
+Known limitations
 =================
 
 This section describes known limitations of the free-threaded CPython build.
@@ -74,7 +74,7 @@ Immortalization
 The free-threaded build of the 3.13 release makes some objects :term:`immortal`
 in order to avoid reference count contention that would prevent efficient
 multi-threaded scaling.  This means that these objects are never deallocated.
-This expected to be addressed in the upcoming 3.14 release with
+This is expected to be addressed in Python 3.14 with
 `deferred reference counting <https://peps.python.org/pep-0703/#deferred-reference-counting>`_.
 
 The objects that are immortalized are:
@@ -93,7 +93,7 @@ returned by :func:`sys.intern` are also immortalized.  This behavior is
 expected to remain in the 3.14 free-threaded build.
 
 
-Frame Objects
+Frame objects
 -------------
 
 It is not safe to access :ref:`frame <frame-objects>` objects from other
@@ -108,12 +108,12 @@ safe and threads may see duplicate or missing elements when iterating or crash
 the interpreter.
 
 
-Single-Threaded Performance
+Single-threaded performance
 ---------------------------
 
 The free-threaded build has additional overhead when executing Python code
 compared to the default GIL-enabled build.  In 3.13, this overhead is about
 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
-Programs that spend most of the their time in C extensions or I/O will see
-less of an impact.  This overhead is expected to be reduced in the upcoming
-3.14 release.
+Programs that spend most of their time in C extensions or I/O will see
+less of an impact.  This overhead is expected to be reduced in the Python
+3.14.

From 1554fb96b4b0fc3371e6038f92e3622bb4436ef8 Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Tue, 24 Sep 2024 09:31:07 -0700
Subject: [PATCH 06/13] Update Doc/howto/free-threading-python.rst

Co-authored-by: mpage <mpage@cs.stanford.edu>
---
 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 22ea04dcc8dbfc..3eaff15866303f 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -115,5 +115,5 @@ The free-threaded build has additional overhead when executing Python code
 compared to the default GIL-enabled build.  In 3.13, this overhead is about
 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
 Programs that spend most of their time in C extensions or I/O will see
-less of an impact.  This overhead is expected to be reduced in the Python
+less of an impact.  This overhead is expected to be reduced in Python
 3.14.

From 3b173e0d648cc447e82d6fc120f458552ffca62d Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Tue, 24 Sep 2024 10:03:32 -0700
Subject: [PATCH 07/13] Update docs

---
 Doc/howto/free-threading-python.rst | 25 +++++++++++++++++--------
 1 file changed, 17 insertions(+), 8 deletions(-)

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
index 3eaff15866303f..2b59d6714c5912 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -1,15 +1,20 @@
 .. _freethreading-python-howto:
 
-*********************************
-Python support for free threading
-*********************************
+**********************************************
+Python experimental 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
+with the :term:`global interpreter lock` (GIL) disabled in a build of Python
 called :term:`free threading`.  This document describes the implications of
 free threading for Python code.  See :ref:`freethreading-extensions-howto` for
 information on how to write C extensions that support the free-threaded build.
 
+.. seealso::
+
+   :pep:`703` – Making the Global Interpreter Lock Optional in CPython for an
+   overall description of free-threaded Python.
+
 
 Installation
 ============
@@ -31,7 +36,7 @@ Identifying free-threaded Python
 
 The free-threaded build of CPython can optionally run with the global
 interpreter lock enabled, such as when :envvar:`PYTHON_GIL` is set to ``1``,
-or when importing an extension module that requires the GIL.
+or automatically when importing an extension module that requires the GIL.
 
 The :func:`sys._is_gil_enabled` function will return ``False`` if the global
 interpreter lock is currently disabled.  This is the recommended mechanism for
@@ -97,8 +102,11 @@ Frame objects
 -------------
 
 It is not safe to access :ref:`frame <frame-objects>` objects from other
-threads.  This means that :func:`sys._current_frames` is generally not safe to
-use in a free-threaded build.
+threads and doing so may cause your program to crash .  This means that
+:func:`sys._current_frames` is generally not safe to use in a free-threaded
+build.  Functions like :func:`inspect.currentframe` and :func:`sys._getframe`
+are generally safe as long as the resulting frame object is not passed to
+another thread.
 
 Iterators
 ---------
@@ -116,4 +124,5 @@ compared to the default GIL-enabled build.  In 3.13, this overhead is about
 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
 Programs that spend most of their time in C extensions or I/O will see
 less of an impact.  This overhead is expected to be reduced in Python
-3.14.
+3.14.   We are aiming for an overhead of 10% or less on the pyperformance
+suite compared to the default GIL-enabled build.

From 91ec1cae09cd3c94be13d8e52a212b2f62ffb718 Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Tue, 24 Sep 2024 14:13:38 -0700
Subject: [PATCH 08/13] Apply suggestions from code review

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
---
 Doc/howto/free-threading-python.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
index 2b59d6714c5912..b89a2a5bf25fb4 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -4,9 +4,8 @@
 Python experimental 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 build of Python
-called :term:`free threading`.  This document describes the implications of
+Starting with the 3.13 release, CPython has experimental support for a build of Python
+called :term:`free threading` where the :term:`global interpreter lock` (GIL) is disabled.  This document describes the implications of
 free threading for Python code.  See :ref:`freethreading-extensions-howto` for
 information on how to write C extensions that support the free-threaded build.
 
@@ -52,12 +51,12 @@ Thread safety
 =============
 
 The free-threaded build of CPython aims to provide similar thread-safety
-behavior at the Python level to the GIL-enabled build.  Built-in
+behavior at the Python level to the default GIL-enabled build.  Built-in
 types like :class:`dict`, :class:`list`, and :class:`set` use internal locks
 to protect against concurrent modifications in ways that behave similarly to
 the GIL.  However, Python has not historically guaranteed specific behavior for
 concurrent modifications to these built-in types, so this should be treated
-as a description of the current implementation, not a guarantee of future
+as a description of the current implementation, not a guarantee of current or future
 behavior.
 
 .. note::
@@ -82,7 +81,8 @@ multi-threaded scaling.  This means that these objects are never deallocated.
 This is expected to be addressed in Python 3.14 with
 `deferred reference counting <https://peps.python.org/pep-0703/#deferred-reference-counting>`_.
 
-The objects that are immortalized are:
+An object will be made immortal when a new thread is started for the first time after the main thread is running.
+The following objects are immortalized:
 
 * :ref:`function <user-defined-funcs>` objects declared at the module level
 * :ref:`method <instance-methods>` descriptors

From 6078cfd54e65c5b7a3c7fc08355194b524500754 Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Tue, 24 Sep 2024 15:04:15 -0700
Subject: [PATCH 09/13] A few more updates

---
 Doc/howto/free-threading-python.rst | 71 +++++++++++++++++------------
 1 file changed, 43 insertions(+), 28 deletions(-)

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
index b89a2a5bf25fb4..1106a5e64de55f 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -4,10 +4,19 @@
 Python experimental support for free threading
 **********************************************
 
-Starting with the 3.13 release, CPython has experimental support for a build of Python
-called :term:`free threading` where the :term:`global interpreter lock` (GIL) is disabled.  This document describes the implications of
-free threading for Python code.  See :ref:`freethreading-extensions-howto` for
-information on how to write C extensions that support the free-threaded build.
+Starting with the 3.13 release, CPython has experimental 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.
+
+This document describes the implications of free threading
+for Python code.  See :ref:`freethreading-extensions-howto` for information on
+how to write C extensions that support the free-threaded build.
 
 .. seealso::
 
@@ -22,24 +31,21 @@ Starting with Python 3.13, the official macOS and Windows installers
 optionally support installing free-threaded Python binaries.  The installers
 are available at https://www.python.org/downloads/.
 
-.. seealso::
+For information on other platforms, see the `Installing a Free-Threaded Python
+<https://py-free-threading.github.io/installing_cpython/>`_, a
+community-maintained installation guide for installing free-threaded Python.
 
-   `Installing a Free-Threaded Python
-   <https://py-free-threading.github.io/installing_cpython/>`_:
-   A community-maintained installation guide for installing free-threaded
-   Python.
+When building CPython from source, the :option:`--disable-gil` configure option
+should be used to build a free-threaded Python interpreter.
 
 
 Identifying free-threaded Python
 ================================
 
-The free-threaded build of CPython can optionally run with the global
-interpreter lock enabled, such as when :envvar:`PYTHON_GIL` is set to ``1``,
-or automatically when importing an extension module that requires the GIL.
-
-The :func:`sys._is_gil_enabled` function will return ``False`` if the global
-interpreter lock is currently disabled.  This is the recommended mechanism for
-decisions like whether to use multithreading or multiprocessing.
+To check if the current interpreter supports free-threading, :option:`python -VV <-V>`
+and :attr:`sys.version` contain "experimental 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.
 
 The ``sysconfig.get_config_var("Py_GIL_DISABLED")`` configuration variable can
 be used to determine whether the build supports free threading.  If the variable
@@ -47,6 +53,18 @@ is set to ``1``, then the build supports free threading.  This is the recommende
 mechanism for decisions related to the build configuration.
 
 
+The global interpreter lock in free-threaded Python
+===================================================
+
+Free-threaded builds of CPython support optionally running with the GIL enabled
+at runtime using the environment variable :envvar:`PYTHON_GIL` or
+the command-line option :option:`-X gil`.
+
+The GIL may also automatically be enabled when importing a C-API extension
+module that is not explicitly marked as supporting free threading.  See 
+:c:macro:`Py_MOD_GIL_NOT_USED` for more details.
+
+
 Thread safety
 =============
 
@@ -56,8 +74,8 @@ types like :class:`dict`, :class:`list`, and :class:`set` use internal locks
 to protect against concurrent modifications in ways that behave similarly to
 the GIL.  However, Python has not historically guaranteed specific behavior for
 concurrent modifications to these built-in types, so this should be treated
-as a description of the current implementation, not a guarantee of current or future
-behavior.
+as a description of the current implementation, not a guarantee of current or
+future behavior.
 
 .. note::
 
@@ -66,7 +84,6 @@ behavior.
    possible.
 
 
-
 Known limitations
 =================
 
@@ -75,14 +92,13 @@ This section describes known limitations of the free-threaded CPython build.
 Immortalization
 ---------------
 
-The free-threaded build of the 3.13 release makes some objects :term:`immortal`
-in order to avoid reference count contention that would prevent efficient
-multi-threaded scaling.  This means that these objects are never deallocated.
-This is expected to be addressed in Python 3.14 with
-`deferred reference counting <https://peps.python.org/pep-0703/#deferred-reference-counting>`_.
+The free-threaded build of the 3.13 release makes some objects :term:`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.
 
-An object will be made immortal when a new thread is started for the first time after the main thread is running.
-The following objects are immortalized:
+An object will be made immortal when a new thread is started for the first time
+after the main thread is running.  The following objects are immortalized:
 
 * :ref:`function <user-defined-funcs>` objects declared at the module level
 * :ref:`method <instance-methods>` descriptors
@@ -90,8 +106,7 @@ The following objects are immortalized:
 * :term:`module` objects and their dictionaries
 * :ref:`classes <classes>` (type objects)
 
-The immortalization of these objects happens the first time a thread is started
-after the main thread.
+
 
 Additionally, numeric and string literals in the code as well as strings
 returned by :func:`sys.intern` are also immortalized.  This behavior is

From e02ed005f23ba72f8c36c20aad797a5407176f6b Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Tue, 24 Sep 2024 15:29:52 -0700
Subject: [PATCH 10/13] Additional comment on immortal objects

---
 Doc/howto/free-threading-python.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
index 1106a5e64de55f..922f963ea2cd15 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -106,7 +106,9 @@ after the main thread is running.  The following objects are immortalized:
 * :term:`module` objects and their dictionaries
 * :ref:`classes <classes>` (type objects)
 
-
+Because immortal objects are never deallocated, applications that create many
+objects of these types may see increased memory usage.  This is expected to be
+addressed in the 3.14 release.
 
 Additionally, numeric and string literals in the code as well as strings
 returned by :func:`sys.intern` are also immortalized.  This behavior is

From 526737ee199fb9ad50cc9598fe46541aa8b750f7 Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Tue, 24 Sep 2024 15:47:02 -0700
Subject: [PATCH 11/13] Mention specializing adaptive interpreter

---
 Doc/howto/free-threading-python.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
index 922f963ea2cd15..27e0ba4eae3cce 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -140,6 +140,9 @@ The free-threaded build has additional overhead when executing Python code
 compared to the default GIL-enabled build.  In 3.13, this overhead is about
 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
 Programs that spend most of their time in C extensions or I/O will see
-less of an impact.  This overhead is expected to be reduced in Python
-3.14.   We are aiming for an overhead of 10% or less on the pyperformance
-suite compared to the default GIL-enabled build.
+less of an impact.  The largest impact is because the specializing adaptive
+interpreter (:pep:`659`) is disabled in the free-threaded build.  We expect
+to re-enable it in a thread-safe way in the 3.14 release.  This overhead is
+expected to be reduced in upcoming Python release.   We are aiming for an
+overhead of 10% or less on the pyperformance suite compared to the default
+GIL-enabled build.

From f24bdb7d3b1b9074fe155492f7ec2bd6128c25db Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Tue, 24 Sep 2024 16:01:11 -0700
Subject: [PATCH 12/13] Remove trailing whitespace

---
 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 27e0ba4eae3cce..05e839cf19a741 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -61,7 +61,7 @@ at runtime using the environment variable :envvar:`PYTHON_GIL` or
 the command-line option :option:`-X gil`.
 
 The GIL may also automatically be enabled when importing a C-API extension
-module that is not explicitly marked as supporting free threading.  See 
+module that is not explicitly marked as supporting free threading.  See
 :c:macro:`Py_MOD_GIL_NOT_USED` for more details.
 
 

From a3ad6b3d75421b10bf5ee628cac405b379c32e6d Mon Sep 17 00:00:00 2001
From: Sam Gross <colesbury@gmail.com>
Date: Wed, 25 Sep 2024 10:48:14 -0700
Subject: [PATCH 13/13] Remove mention of C macro

---
 Doc/howto/free-threading-python.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/Doc/howto/free-threading-python.rst b/Doc/howto/free-threading-python.rst
index 05e839cf19a741..b21e3287ecaa3f 100644
--- a/Doc/howto/free-threading-python.rst
+++ b/Doc/howto/free-threading-python.rst
@@ -61,8 +61,14 @@ at runtime using the environment variable :envvar:`PYTHON_GIL` or
 the command-line option :option:`-X gil`.
 
 The GIL may also automatically be enabled when importing a C-API extension
-module that is not explicitly marked as supporting free threading.  See
-:c:macro:`Py_MOD_GIL_NOT_USED` for more details.
+module that is not explicitly marked as supporting free threading.  A warning
+will be printed in this case.
+
+In addition to individual package documentation, the following websites track
+the status of popular packages support for free threading:
+
+* https://py-free-threading.github.io/tracking/
+* https://hugovk.github.io/free-threaded-wheels/
 
 
 Thread safety

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>pFad - Phonifier reborn</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
</head>
<body>
<h1>Pfad - The Proxy pFad of &#169; 2024 Garber Painting. All rights reserved.</h1>


<!-- Disclaimer -->
<p>Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.</p>
<br>
<p>Alternative Proxies:</p><p><a href="http://clevelandohioweatherforecast.com/php-proxy/index.php?q=https://patch-diff.githubusercontent.com/raw/python/cpython/pull/124371.patch" target="_blank">Alternative Proxy</a></p><p><a href="http://clevelandohioweatherforecast.com/pFad/index.php?u=https://patch-diff.githubusercontent.com/raw/python/cpython/pull/124371.patch" target="_blank">pFad Proxy</a></p><p><a href="http://clevelandohioweatherforecast.com/pFad/v3index.php?u=https://patch-diff.githubusercontent.com/raw/python/cpython/pull/124371.patch" target="_blank">pFad v3 Proxy</a></p><p><a href="http://clevelandohioweatherforecast.com/pFad/v4index.php?u=https://patch-diff.githubusercontent.com/raw/python/cpython/pull/124371.patch" target="_blank">pFad v4 Proxy</a></p></body>
</html>