[3.11] gh-103059: Clarify gc.freeze documentation (GH-103058) (#103416)

gh-103059: Clarify gc.freeze documentation (GH-103058)
(cherry picked from commit 8b1b17134e2241a8cdff9e0c869013a7ff3ca2fe)

Co-authored-by: raylu <lurayl@gmail.com>

diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst
index 69a1a8313b7593104986cac131d9c189b1415cc2..42bb6dc3503f7576d8f833bbdc12fdc8a9b2eab9 100644 (file)
--- a/Doc/library/gc.rst
+++ b/Doc/library/gc.rst
@@ -206,12 +206,17 @@ The :mod:`gc` module provides the following functions:
 
 .. function:: freeze()
 
-   Freeze all the objects tracked by gc - move them to a permanent generation
-   and ignore all the future collections. This can be used before a POSIX
-   fork() call to make the gc copy-on-write friendly or to speed up collection.
-   Also collection before a POSIX fork() call may free pages for future
-   allocation which can cause copy-on-write too so it's advised to disable gc
-   in parent process and freeze before fork and enable gc in child process.
+   Freeze all the objects tracked by the garbage collector; move them to a
+   permanent generation and ignore them in all the future collections.
+
+   If a process will ``fork()`` without ``exec()``, avoiding unnecessary
+   copy-on-write in child processes will maximize memory sharing and reduce
+   overall memory usage. This requires both avoiding creation of freed "holes"
+   in memory pages in the parent process and ensuring that GC collections in
+   child processes won't touch the ``gc_refs`` counter of long-lived objects
+   originating in the parent process. To accomplish both, call ``gc.disable()``
+   early in the parent process, ``gc.freeze()`` right before ``fork()``, and
+   ``gc.enable()`` early in child processes.
 
    .. versionadded:: 3.7
 

diff --git a/Misc/ACKS b/Misc/ACKS
index dbcff1e15435e35faf32c08ed20eeb5462356fe6..c7c0677c5ba13916682493e3e04a06ee3a778649 100644 (file)
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1103,6 +1103,7 @@ Jason Lowe
 Tony Lownds
 Ray Loyzaga
 Kang-Hao (Kenny) Lu
+Raymond Lu
 Lukas Lueg
 Loren Luke
 Fredrik Lundh