Clarify the Purpose of the PyGILState API and Identify Better Alternatives

This especially applies to the following sections:

• https://docs.python.org/3/c-api/init.html#c.PyGILState_Ensure
• https://docs.python.org/3/c-api/init.html#c.PyGILState_Release

but also:

• https://docs.python.org/3/c-api/init.html#c.PyGILState_GetThisThreadState
• https://docs.python.org/3/c-api/init.html#c.PyGILState_Check

The PyGILState_* C-API was introduced by PEP 311 as a convenience for extension maintainers for some very specific situations:

• code running in the current thread does not know if it holds the GIL
• this situation may involve reentrancy

The PyGILState_* API also (almost incidentally) supports use cases that are more appropriately satisfied by other API, like Py_BEGIN_ALLOW_THREADS()/Py_END_ALLOW_THREADS() for balanced acquire-release.

The documentation isn't so clear about the specific use cases, nor that an interested user may actually want a different API. For example, from a recent issue I saw: We were wrapping each evaluation in PyGILState_Ensure and PyGILState_Release, which I believe is a correct way to do this.

FTR, https://docs.python.org/3/c-api/init.html#non-python-created-threads does a decent job of explaining, as does the PEP, but the entries for PyGILState_Ensure() and PyGILState_Release() are less clear.

FWIW, I expect that it is easier now to deal with the motivating cases using the exiting C-API than it was in 2003. I'm not sure we would accept something like PEP 311 if it were proposed today. Then again, for a pair of operations that needs to balanced like this, having a specific pair of functions is helpful.

Related: a recent discussion about replacing the PyGILState_* API: https://discuss.python.org/t/a-new-api-for-ensuring-releasing-thread-states/83959.

Also see gh-131264 and gh-131265.

Beginne mit den Dokumentationseinträgen zu PyGILState_Ensure(), PyGILState_Release(), PyGILState_GetThisThreadState() und PyGILState_Check(), und vergleiche sie anschließend mit PEP 311, dem Abschnitt zu Threads, die nicht von Python erstellt wurden, und der verlinkten Diskussion. Als abgeschlossen gilt die Aufgabe, wenn die Einträge ihre vorgesehenen Anwendungsfälle klar erläutern und Leser gegebenenfalls auf bessere Alternativen verweisen.