Skip to content

Commit d0baebf

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 2cdc518 commit d0baebf

File tree

2 files changed

+12
-3
lines changed

2 files changed

+12
-3
lines changed

Doc/library/gc.rst

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,14 @@ The :mod:`gc` module provides the following functions:
3232

3333
Disable automatic garbage collection.
3434

35+
This can be useful for a process that will fork() but not exec() to do at
36+
the beginning of the parent's execution. When the collector runs in the
37+
parent, it leaves space scattered throughout memory pages for new objects.
38+
Those pages become shared as copy-on-write pages with the child after forking.
39+
When the child starts allocating objects, it writes to those pages, causing
40+
the kernel to copy them, including all the garbage data the parent had
41+
already collected. Remember to re-enable collection in the child.
42+
3543

3644
.. function:: isenabled()
3745

@@ -209,9 +217,9 @@ The :mod:`gc` module provides the following functions:
209217
Freeze all the objects tracked by gc - move them to a permanent generation
210218
and ignore all the future collections. This can be used before a POSIX
211219
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.
220+
Otherwise, when the child process accesses objects allocated in the parent,
221+
the gc_refs counter will be incremented, triggering copy-on-write and
222+
consuming more memory.
215223

216224
.. versionadded:: 3.7
217225

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)