From a2f9896a712d7495abf167ce1476246431ff7f2f Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Mon, 14 Oct 2024 13:19:51 +0300
Subject: [PATCH] Retarget incremental GC changes to 3.14

---
 Doc/library/gc.rst    |  8 +++---
 Doc/whatsnew/3.14.rst | 67 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst
index 1065ec30802841..b501dfcf15702e 100644
--- a/Doc/library/gc.rst
+++ b/Doc/library/gc.rst
@@ -60,7 +60,7 @@ The :mod:`gc` module provides the following functions:
    The effect of calling ``gc.collect()`` while the interpreter is already
    performing a collection is undefined.
 
-   .. versionchanged:: 3.13
+   .. versionchanged:: 3.14
       ``generation=1`` performs an increment of collection.
 
 
@@ -83,13 +83,13 @@ The :mod:`gc` module provides the following functions:
    returned. If *generation* is not ``None``, return only the objects as follows:
 
    * 0: All objects in the young generation
-   * 1: No objects, as there is no generation 1 (as of Python 3.13)
+   * 1: No objects, as there is no generation 1 (as of Python 3.14)
    * 2: All objects in the old generation
 
    .. versionchanged:: 3.8
       New *generation* parameter.
 
-   .. versionchanged:: 3.13
+   .. versionchanged:: 3.14
       Generation 1 is removed
 
    .. audit-event:: gc.get_objects generation gc.get_objects
@@ -137,7 +137,7 @@ The :mod:`gc` module provides the following functions:
 
    See `Garbage collector design <https://devguide.python.org/garbage_collector>`_ for more information.
 
-   .. versionchanged:: 3.13
+   .. versionchanged:: 3.14
       *threshold2* is ignored
 
 
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index 25e69a59bdec62..e1908133601776 100644
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -172,6 +172,29 @@ Improved Error Messages
      ValueError: too many values to unpack (expected 3, got 4)
 
 
+.. _whatsnew314-incremental-gc:
+
+Incremental garbage collection
+------------------------------
+
+The cycle garbage collector is now incremental.
+This means that maximum pause times are reduced
+by an order of magnitude or more for larger heaps.
+
+There are now only two generations: young and old.
+When :func:`gc.collect` is not called directly, the
+GC is invoked a little less frequently. When invoked, it
+collects the young generation and an increment of the
+old generation, instead of collecting one or more generations.
+
+The behavior of :func:`!gc.collect` changes slightly:
+
+* ``gc.collect(1)``: Performs an increment of garbage collection,
+  rather than collecting generation 1.
+* Other calls to :func:`!gc.collect` are unchanged.
+
+(Contributed by Mark Shannon in :gh:`108362`.)
+
 Other Language Changes
 ======================
 
@@ -283,6 +306,35 @@ functools
   (Contributed by Dominykas Grigonis in :gh:`119127`.)
 
 
+gc
+--
+
+The cyclic garbage collector is now incremental,
+which changes the meaning of the results of
+:meth:`~gc.get_threshold` and :meth:`~gc.set_threshold`
+as well as :meth:`~gc.get_count` and :meth:`~gc.get_stats`.
+
+* For backwards compatibility, :meth:`~gc.get_threshold` continues to return
+  a three-item tuple.
+  The first value is the threshold for young collections, as before;
+  the second value determines the rate at which the old collection is scanned
+  (the default is 10, and higher values mean that the old collection
+  is scanned more slowly).
+  The third value is meaningless and is always zero.
+
+* :meth:`~gc.set_threshold` ignores any items after the second.
+
+* :meth:`~gc.get_count` and :meth:`~gc.get_stats` continue to return
+  the same format of results.
+  The only difference is that instead of the results referring to
+  the young, aging and old generations,
+  the results refer to the young generation
+  and the aging and collecting spaces of the old generation.
+
+In summary, code that attempted to manipulate the behavior of the cycle GC
+may not work exactly as intended, but it is very unlikely to be harmful.
+All other code will work just fine.
+
 http
 ----
 
@@ -415,6 +467,14 @@ asyncio
   reduces memory usage.
   (Contributed by Kumar Aditya in :gh:`107803`.)
 
+gc
+--
+
+* The new :ref:`incremental garbage collector <whatsnew314-incremental-gc>`
+  means that maximum pause times are reduced
+  by an order of magnitude or more for larger heaps.
+  (Contributed by Mark Shannon in :gh:`108362`.)
+
 Deprecated
 ==========
 
@@ -617,6 +677,13 @@ Changes in the Python API
   Wrap it in :func:`staticmethod` if you want to preserve the old behavior.
   (Contributed by Serhiy Storchaka and Dominykas Grigonis in :gh:`121027`.)
 
+* The :ref:`garbage collector is now incremental <whatsnew314-incremental-gc>`,
+  which means that the behavior of :func:`gc.collect` changes slightly:
+
+  * ``gc.collect(1)``: Performs an increment of garbage collection,
+    rather than collecting generation 1.
+  * Other calls to :func:`!gc.collect` are unchanged.
+
 * The :func:`locale.nl_langinfo` function now sets temporarily the ``LC_CTYPE``
   locale in some cases.
   This temporary change affects other threads.