Clarifying the PyGILState_ API for per-GIL subinterpreters

[ZeroIntensity]

Documentation

Both #123488 and #123134 have made it clear that PEP-684 and multithreading from C haven't been documented properly. In both issues, the following line was misinterpreted:

Python supports the creation of additional interpreters (using Py_NewInterpreter()), but mixing multiple interpreters and the PyGILState_* API is unsupported.

This has been interpreted as "it's safe to call Py_NewInterpreter (or Py_NewInterpreterFromConfig) without the GIL," which it definitely is not! It's just that we can't switch interpreters via PyGILState_* -- that should be clarified.

(@encukou, this needs topic-subinterpreters)

Linked PRs

• gh-123672: Clarify the usage of PyGILState* for subinterpreters #123728