gh-103059: Clarify gc.freeze documentation

[raylu]

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.

• Issue: gc.freeze documentation is unclear #103059

[bedevere-bot]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-bot]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

[carljm]

Thanks for the proposal and PR!

I definitely agree that the gc.freeze() docs should be cleaned up and clarified, but I don't agree with adding a bunch of fork-specific text to the gc.disable() docs. There are lots of possible reasons to disable GC; "I'm going to fork-without-exec later" is only one of them, and probably not the most common. And in that use case, gc.disable() is still useless unless you also gc.freeze(). So the only API that is specific to the fork-without-exec use case is gc.freeze(), and the explanation of how to handle fork-without-exec belongs there.

Here's my full suggested rewrite for the gc.freeze() documentation:

Freeze all objects tracked by the garbage collector: move them to a permanent generation and ignore them in all 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 memory 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.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[raylu]

I left in the bit about gc_refs (I feel like this was critical to my understanding of freeze) but otherwise went with your explanation and left gc.disable() untouched

I have made the requested changes; please review again

[bedevere-bot]

Thanks for making the requested changes!

@carljm: please review the changes made to this pull request.

[carljm]

This change looks accurate and like a solid improvement to me. Thanks for the PR!

Process nit for future contributions to CPython: it's better to never force-push your PR. It can make life more difficult for reviewers (can't see changes since previously-reviewed version), and there's no benefit, since we always squash on merge anyway.

[miss-islington]

Thanks @raylu for the PR, and @carljm for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-103416 is a backport of this pull request to the 3.11 branch.