From f14f2be3d9b802a768417b8fb7d8e6767a241d0b Mon Sep 17 00:00:00 2001 From: raylu Date: Mon, 10 Apr 2023 09:30:32 -0700 Subject: [PATCH] gh-103059: Clarify gc.freeze documentation (#103058) --- Doc/library/gc.rst | 17 +++++++++++------ Misc/ACKS | 1 + 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst index 832ebaf497f37ab..6d5c64df1a1f3fa 100644 --- 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 49f3692dfd6b8f3..1e94d33a665e4c6 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1115,6 +1115,7 @@ Jason Lowe Tony Lownds Ray Loyzaga Kang-Hao (Kenny) Lu +Raymond Lu Lukas Lueg Loren Luke Fredrik Lundh