Repository navigation
Document the new incremental GC #117759
Description
Activity
Please, also modify https://github.com/python/devguide/blob/main/internals/garbage-collector.rst to keep it in sync with the current implementation
- Reacted by Pablo Galindo Salgado and Savannah Ostrowski
Thanks 🙏
For the reader, it is confusing that in 3.13
Generation 1 is removed, but also*threshold2* is ignored. One would expectthreshold1to be what is ignored if it is generation 1 that is removed. Previously, the role ofthreshold2was never documented anyway. Butthreshold1was documented, and it related to generation 1, not generation 2.Also, the document indicates no change to the values returned by
get_threshold(), which leaves one wondering about whether the threshold for generation 2 is reflected in the third value (as previously) or whether the second value now holds the threshold for generation 2. Without checking, I have no idea.(To me it would have made sense to simply change the signatures and return values of all functions that assumed there were three generations, and then document the changes as simply only having two generations now, rather than saying one is removed. If you're already introducing breaking changes in the way something works, then why leave the cruft of extra ignored parameters and undefined or blank return values? But if the goal is some misguided idea of compatibility (even though they fundamentally are not compatible) such that
For compatibility, gc.get_objects() pretends there is a generation 1, then the same should apply to the values returned byget_threshold()and accepted byset_threshold(), in which casethreshold1rather thanthreshold2should be ignored.)Also, the document speaks in three places of
the collection frequency. Can someone propose a better, less confusing wording? Frequency is count divided by time. But the so-called "frequency" of collection has nothing to do with time. If these are, as the function and argument names indicate, thresholds in a cycle, then it seems like it should talk about "collection cycle parameters" or something like that rather than frequency. Similarly, time words like "slower" are used when it's not about time:The larger threshold1 is, the slower objects in the old generation
are collected.So it's also confusing when the document equates the thresholds with "frequency" when they are inverse to "frequency":
Set the garbage collection thresholds (the collection frequency).
Related to this issue is #122862. It points out that the running calculation of
the number of allocations minus the number of deallocationssince the last collectionis never allowed to go below 0, so the current description is inaccurate. The same problem exists indevguide/internals/garbage-collector.rstAlso, it is noted that
Setting *threshold0* to zero disables collection.However, this is confusing because this is a totally different kind of disablement than spoken of elsewhere in the document. In other words,gc.isenabled()will still returnTrue, andgc.enable()does not actually enable collection whenthreshold0is zero. Using a different word like "inhibit" or "prevent" rather than "disable" might help to avoid confusion. And if negative values achieve the same thing as zero (don't know, just guessing), then it should be stated as "less than one".(Actually, the better option would be for
set_thresholdto implement proper bounds checking in the first place, so setting less than one would result in an exception. Then you don't have to document stupid edge cases or distinguish between different kinds of disablement. Currently, you can set thresholds as low as -0x80000000, yet both this and the devguide say the threshold is inverse to the "frequency", but that's not true for more than half the possible values the function accepts.)
Documentation
Linked PRs