Skip to content

Commit faee1cf

Browse files
committed
gh-103059: Move fork advice from gc.freeze to gc.disable
The current advice seems to mean you should gc.disable() and gc.freeze() right before os.fork(), which doesn't do anything. Łukasz explained the advice in https://bugs.python.org/issue31558#msg302780. This moves the advice around gc.disable out of the gc.freeze docs.
1 parent 24ba507 commit faee1cf

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
@@ -1113,6 +1113,7 @@ Jason Lowe
11131113
Tony Lownds
11141114
Ray Loyzaga
11151115
Kang-Hao (Kenny) Lu
1116+
Raymond Lu
11161117
Lukas Lueg
11171118
Loren Luke
11181119
Fredrik Lundh

0 commit comments

Comments
 (0)