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

Start by reviewing the PyGILState_Check() C-API entry point and the runtime history summarized in the issue, including the proposed Py_HoldsGIL() name. Determine the required public API and compatibility changes; the work is done when the rename is agreed and consistently reflected in the relevant API surface and tests.