GH-124742: Add the PYTHON_GC_THRESHOLD environment variable.

[nascheme]

• Issue: Add PYTHON_GC_THRESHOLD env var #124742

Some comments of the approach taken here:

• I want to keep this change as simple as possible and as robust as possible, in case it is deemed safe enough to merge into 3.13. Getting it into 3.13 could increase the amount of useful feedback from real apps, improving our decision making for the 3.14 release. It is quite likely we change things related to this threshold.
• In the 'main' branch, I plan to make a corresponding -X option for it and to put it into the config structure, so it can be set for embedding scenarios
• This is a low level "tuning knob" and I think a high level knob would actually be more useful (e.g. PYTHON_GC_STRATEGY) as proposed on the Ideas forum. However, for 3.13 it seems safest to do the simplest possible thing and that's exposing the threshold0 setting to be set by an env var.
• I didn't raise an error if the env var value is invalid. For the 'main' branch version, I would put that error in, so that an invalid setting doesn't pass silently.

---

📚 Documentation preview 📚: https://cpython-previews--124743.org.readthedocs.build/

[ZeroIntensity]

Hmm, why ignore the error? If a user accidentally sets the variable to something that doesn't work, then they might end up very confused as to why Python is ignoring their request.

[nascheme]

I'm hoping this change can be included in the 3.13 RC and so I wanted it as simple and robust as possible. In the 'main' branch, I plan to re-work it so it becomes part of the config structure and I would add an error raise there.

Maybe it is safe enough to raise an error here too. That would be consistent with the principle that "errors should not pass silently".

[ZeroIntensity]

I think that making it return an error rather than nothing should still remain fairly simple, return will just become return _PyStatus_ERR("...") and whatnot.

I haven't paid too much attention to the incremental GC problem (#124567), but I'm assuming that this is a possible solution for it? That should help it go into the 3.13 release

[nascheme]

No, I don't think this would be enough for us to feel safe about including incremental GC into 3.13. In retrospect, the incremental GC should have been opt-in for 3.13 and would become default in 3.14 if people had good experience with it.

The point of this env var is to increase the chances that people will test their programs with a higher threshold with 3.13 and then when 3.14 release nears, we would have a better idea about how "aggressive" the default GC tuning should be.

[nascheme]

Returning an error _PyGC_Init results in this kind of error:

Fatal Python error: _PyGC_Init: Invalid PYTHON_GC_THRESHOLD value.
Python runtime state: preinitialized

Current thread 0x00007fe0505d6740 (most recent call first):
  <no Python frame>

[ZeroIntensity]

I think that makes sense. We do the same for other env vars.

[Eclips4]

I'm hoping this change can be included in the 3.13 RC and so I wanted it as simple and robust as possible.

Since we have already reached the feature-freeze stage and this is a new feature, it needs confirmation from @Yhg1s.

[nascheme]

That's right. It's Thomas's call and I completely understand if he doesn't want it. There has already been a bit too much excitement with the RCs.

[nascheme]

Closing. RC3 is out and I think GH-124772 is a better API to put into the main branch.