Documentation should specify if the GIL helpers are reentrant and if they can be called without an ambient GIL

[ezyang]

In https://pybind11.readthedocs.io/en/stable/advanced/misc.html#global-interpreter-lock-gil it says that gil_scoped_release and gil_scoped_acquire are available, and doesn't elaborate further. But there are some important correctness conditions related to the use of these functions:

1. Is it valid to gil_scoped_acquire, and then immediately gil_scoped_acquire again? (I... think this is supposed to be yes?) Ditto with gil_scoped_release. (I have no idea! See 3)
2. Is it OK to mix these functions with traditional PyGILState functions? (According to #1276, no)
3. Is it OK to call gil_scoped_release in a context where you never had the GIL to begin with? (Empirically, no.)

The documentation should address all these questions.

[harsh1995]

Any update on this?

[Tishj]

Looking at the destructor of gil_scoped_release it seems the answer to 3 is that this is allowed

    ~gil_scoped_release() {
        if (!tstate) {
            return;
        }

Which is probably to make nesting of gil_scoped_release objects a no-op (?)