Documentation should specify if the GIL helpers are reentrant and if they can be called without an ambient GIL
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 18k
- Forks
- 2.3k
- Avg merge
- 5d 17h
- Merged PRs (30d)
- 10
Description
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:
- 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)
- Is it OK to mix these functions with traditional PyGILState functions? (According to #1276, no)
- 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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the GIL section in advanced/misc.html and review issue #1276 for the existing guidance on PyGILState functions. Verify the documented behavior of gil_scoped_acquire and gil_scoped_release for nested calls, mixing with traditional GIL APIs, and release without an ambient GIL. Done means the documentation answers all three questions with clear correctness conditions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100