Rename PyGILState_Check()

Feature or enhancement

Proposal:

Nearly all of the C-API expects that the current thread holds the GIL when called. Mostly, users of the C-API had to know before calling the C-API. Beck in the day it wasn't obvious how. This was the motivation behind adding PyGILState_Check().

The key point in this issue is that the name PyGILState_Check() unnecessarily associates the capability with the PyGILState_* API. Users would benefit from a different function name. I'd think something like Py_HoldsGIL() would be better.

Why was the function added as PyGILState_Check()? Perhaps @kristjanvalur remembers. It was added in 2013, 10 years after the PEP 311 implementation, so it's not because it was part of the PEP. I'd guess it's mostly because it was implemented using PyGILState_GetThisThreadState().

It's also notable that a lot of things have changed in the runtime since 2013. At the time PyGILState_Check() was added:

• you could use PyThreadState_Get() (or PyThreadState_GET()) to get the tstate active in the current thread, but only if it held the GIL
• you could get the last active tstate in the current thread using PyGILState_GetThisThreadState()
• internally there was a static PyThreadState_IsCurrent() that sort of merged the two

Here some of the developments since then:

• every tstate now knows whether or not it holds the GIL
• the runtime now keeps track of the last tstate to hold the GIL
• the current tstate has moved from a global variable to a thread-local variable
• each interpreter now has its own GIL

Here's the history in some detail:

Has this already been discussed elsewhere?

No response given

Links to previous discussion of this feature:

No response

Inizia esaminando l’entry point della C-API PyGILState_Check() e la cronologia del runtime riassunta nell’issue, incluso il nome proposto Py_HoldsGIL(). Determina le modifiche necessarie all’API pubblica e alla compatibilità; il lavoro è completo quando il rinominamento è concordato e riflesso in modo coerente nella superficie dell’API interessata e nei test.