Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 10, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions Doc/library/gc.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions Misc/ACKS
Original file line number Diff line number Diff line change
Expand Up @@ -1103,6 +1103,7 @@ Jason Lowe
Tony Lownds
Ray Loyzaga
Kang-Hao (Kenny) Lu
Raymond Lu
Lukas Lueg
Loren Luke
Fredrik Lundh
Expand Down