gh-127989: C API: Refer to attached thread states instead of the GIL

[ZeroIntensity]

As I said in the issue, this is a big change, but it should help clear things up for users. Any feedback, or pointing out flaws, is definitely appreciated!

• Issue: Refer to the GIL as a thread state in the C API #127989

---

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

[ncoghlan]

Ping @ericsnowcurrently (I don't think this is urgent enough to override another core dev's "changes requested" flag, but I also don't agree with all of Eric's suggested changes, so we need clarification of which comments were the ones specifically intended to be merge blocking)

[ZeroIntensity]

Ok, I've come up with a compromise here. There seems to be quite a bit of opposition to calling this a "runtime context," so I've kept the phrase "thread state," but I've changed the glossary definitions to mostly fit Eric's suggestions. At the bottom of the "attached thread state" definition, I've added a note about free-threading:

In free-threaded builds of Python, threads can concurrently hold an attached thread state, allowing for true parallelism of the bytecode interpreter.

I think this is an important part to emphasize--from the user's perspective, all free-threading really does is allow for multiple active thread states at a time, and that gives a good intuitive sense of why things like PyGILState_Ensure are still needed on FT builds. If there's any other places we should try to mention this, let me know.

Regarding this part:

current does not imply attached, but attached does implies current

I decided just to drop any mention of the "current thread-local state pointer" and just replaced everything with being either "attached" or not. It's probably better to keep how we expose thread states out of the documentation.

So, with all that in mind: I didn't expect the Spanish Inquisition

[bedevere-app]

Nobody expects the Spanish Inquisition!

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

[vstinner]

LGTM. I'm fine with "attached thread state" and "active thread state".

[encukou]

LGTM; I'll merge ~tomorrow if there are no objections.

IMO, it's fine to have C API details in the glossary for terms related to the C API -- which these are.

My main worry is that per the SC's pronouncement on PEP 703, all changes related to free-threading should be revertable. Unfortunately, we can't really put #ifs in the docs, so the revert will need to start with a manual search for "free-threading".
But, I expect the term "attached thread state" -- and so, the bulk of the changes here -- to stay even if nogil needs to be abandoned for some reason.

[encukou]

Oh, I missed the change request (is it just me or were these more prominent not that long ago?)

@ericsnowcurrently, do you want to block this iteration?

[ericsnowcurrently]

No real objections; I defer to you, Victor and Alyssa.

[vstinner]

I already approved the PR :-)

[encukou]

Thanks! Let's build on this :)