Add optional `wait_if_running` argument to `gc.collect()`

[colesbury]

Feature or enhancement

Background

The gc.collect() documentation states:

The effect of calling gc.collect() while the interpreter is already performing a collection is undefined.

In practice, gc.collect() will return immediately if it's already running, including re-entrant calls from the same thread (i.e., from object finalizers) and if the GC happens to be running in another thread. Note that even with the GIL, the GC isn't completely atomic: running tp_clear and object finalizes (i.e., __del__ functions) can release the GIL and allow another thread to run concurrently.

Motivation

Both CPython and third-party packages often use gc.collect() in tests to ensure that cycles are collected and, in the free threading build, any delayed reference count operations are processed when testing for things related to object lifetimes.

The problem is that these tests can be flaky if multiple threads are used, because if one thread happens to be running the GC, then the gc.collect() in another thread returns immediately without doing anything. This happens more frequently in the free threading build because there are more opportunities for interleaving between threads and because of things like biased reference counting that can lead to delayed object destructors.

Proposal

Add a keyword-only argument wait_if_running to gc.collect(). The default value is wait_if_running=False, which preserves the current behavior. If wait_if_running=True:

• If the GC is running in a different thread, then the call will wait until that GC finishes and then run the GC.
• If the GC is running in the caller's thread, then the call will raise an exception so as to avoid deadlock.

cc @hawkinsp

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

[sergey-miryanov]

Maybe it is worth to add a private function to a test.support, for example? I'm afraid that, once it becomes public, it will be used incorrectly and users will face nondeterministic freezes with gc.collect.

[ngoldbaum]

I think this API would allow PyO3 to clean this hacky testing code up: https://github.com/PyO3/pyo3/blob/a202d8df9c595820aa4c8c347cee7e513f8bed81/tests/test_gc.rs#L99-L123

[hawkinsp]

Maybe it is worth to add a private function to a test.support, for example? I'm afraid that, once it becomes public, it will be used incorrectly and users will face nondeterministic freezes with gc.collect.

This is something that end users may need to do in their tests, if they want to be sure that garbage collection ran at a particular program point. A private function does not help.

[ZeroIntensity]

Maybe it is worth to add a private function to a test.support, for example? I'm afraid that, once it becomes public, it will be used incorrectly and users will face nondeterministic freezes with gc.collect.

test.support (and the entire test module) isn't shipped to users. I think incorrect usage can be avoided by just documenting wait_if_running as being useful for multithreaded tests.