Skip to content

Commit b80e4c8

Browse files
[3.11] gh-103059: Clarify gc.freeze documentation (GH-103058) (#103416)
gh-103059: Clarify gc.freeze documentation (GH-103058) (cherry picked from commit 8b1b171) Co-authored-by: raylu <lurayl@gmail.com>
1 parent 0f6319f commit b80e4c8

File tree

2 files changed

+12
-6
lines changed

2 files changed

+12
-6
lines changed

Doc/library/gc.rst

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -206,12 +206,17 @@ The :mod:`gc` module provides the following functions:
206206

207207
.. function:: freeze()
208208

209-
Freeze all the objects tracked by gc - move them to a permanent generation
210-
and ignore all the future collections. This can be used before a POSIX
211-
fork() call to make the gc copy-on-write friendly or to speed up collection.
212-
Also collection before a POSIX fork() call may free pages for future
213-
allocation which can cause copy-on-write too so it's advised to disable gc
214-
in parent process and freeze before fork and enable gc in child process.
209+
Freeze all the objects tracked by the garbage collector; move them to a
210+
permanent generation and ignore them in all the future collections.
211+
212+
If a process will ``fork()`` without ``exec()``, avoiding unnecessary
213+
copy-on-write in child processes will maximize memory sharing and reduce
214+
overall memory usage. This requires both avoiding creation of freed "holes"
215+
in memory pages in the parent process and ensuring that GC collections in
216+
child processes won't touch the ``gc_refs`` counter of long-lived objects
217+
originating in the parent process. To accomplish both, call ``gc.disable()``
218+
early in the parent process, ``gc.freeze()`` right before ``fork()``, and
219+
``gc.enable()`` early in child processes.
215220

216221
.. versionadded:: 3.7
217222

Misc/ACKS

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1103,6 +1103,7 @@ Jason Lowe
11031103
Tony Lownds
11041104
Ray Loyzaga
11051105
Kang-Hao (Kenny) Lu
1106+
Raymond Lu
11061107
Lukas Lueg
11071108
Loren Luke
11081109
Fredrik Lundh

0 commit comments

Comments
 (0)