8000 Docs: C API: Improve documentation around non-Python threads with subinterpreters by ZeroIntensity · Pull Request #131087 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

Docs: C API: Improve documentation around non-Python threads with subinterpreters #131087

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 17, 2025
Merged

Docs: C API: Improve documentation around non-Python threads with subinterpreters #131087

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1b10658
Document some examples and notes about non-Python threads with subint…
ZeroIntensity Mar 11, 2025
1afcbb7
Add clarification to 'only if'
ZeroIntensity Mar 19, 2025
2e3d5d7
Merge branch 'main' into document-gilstate-subinterpreters
ZeroIntensity Mar 20, 2025
660aa77
Switch to thread state terms instead of the silly GIL
ZeroIntensity Mar 24, 2025
961d8b9
Update init.rst
ZeroIntensity May 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Switch to thread state terms instead of the silly GIL
  • Loading branch information
@ZeroIntensity
ZeroIntensity authored Mar 24, 2025
commit 660aa77bfa27d16ff4bd8ce9c35f1ccc0c88f01d
13 changes: 6 additions & 7 deletions Doc/c-api/init.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1084,8 +1084,9 @@ interpreter (created automatically by :c:func:`Py_Initialize`). Python
supports the creation of additional interpreters (using
:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the
``PyGILState_*`` API is unsupported. This is because :c:func:`PyGILState_Ensure`
and similar functions almost always acquire the :term:`GIL` of the main interpreter
in threads created by subinterpreters, which can lead to data races or deadlocks.
and similar functions default to :term:`attaching <attached thread state>` a
:term:`thread state` for the main interpreter, meaning that the thread can't safely
interact with the calling subinterpreter.

Supporting subinterpreters in non-Python threads
------------------------------------------------
Expand All @@ -1094,11 +1095,9 @@ If you would like to support subinterpreters with non-Python created threads, yo
must use the ``PyThreadState_*`` API instead of the traditional ``PyGILState_*``
API.

In particular, you must store the exact interpreter state from the calling
function and pass it to :c:func:`PyThreadState_New` to ensure that the thread
acquires the :term:`GIL` of the subinterpreter instead of the main interpreter.
In turn, this means that the return value of :c:func:`PyInterpreterState_Get`
should be stored alongside any information passed to the thread.::
In particular, you must store the interpreter state from the calling
function and pass it to :c:func:`PyThreadState_New`, which will ensure that
the :term:`thread state` is targeting the correct interpreter.::

/* The return value of PyInterpreterState_Get() from the
function that created this thread. */
Expand Down
Loading
0