Docs: C API: Improve documentation around non-Python threads with subinterpreters by ZeroIntensity · Pull Request #131087 · python/cpython

ZeroIntensity · 2025-03-11T12:54:19Z

@da-woods's comment inspired me to improve some of the documentation here. This should play pretty nicely with the incoming PyThreadState_Ensure API, and with GH-127990 whenever that gets merged.

Add a section + example using PyThreadState * to support subinterpreters in a non-Python thread.
Upgrade PyGILState_Ensure's note to a warning, and mention that it can actually crash the interpreter. (See Debug build assertion failure with native threads attempting to acquire GIL on termination #131012 and PyGILStateEnsure() (Probably) Crashes If Called After Finalization #124619.)
Note that PyGILState_Check always returns 1 if subinterpreters are enabled.
Note that PyGILState_GetThisThreadState doesn't account for non-GILState thread states.
Note that PyThreadState_Swap will also hang the thread during finalization (but unlike GILState, it shouldn't crash).

📚 Documentation preview 📚: https://cpython-previews--131087.org.readthedocs.build/en/131087/c-api/init.html#supporting-subinterpreters-in-non-python-threads

…erpreters.

sharktide · 2025-03-17T15:59:40Z

I can make backport if review passes

ZeroIntensity · 2025-03-20T12:09:54Z

I'll deal with resolving conflicts later today.

ZeroIntensity · 2025-03-24T14:44:27Z

I've opted to not backport this because we're using thread state terms now.

sharktide · 2025-03-24T21:30:32Z

ok :)

…

On Mon, Mar 24, 2025 at 10:44 AM Peter Bierma ***@***.***> wrote: I've opted to not backport this because we're using thread state terms now. — Reply to this email directly, view it on GitHub <#131087 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNITW56N5GH66FQNT6MXOHT2WAK6FAVCNFSM6AAAAABYY2QLM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBYGM3TQNZSGE> . You are receiving this because you commented.Message ID: ***@***.***> [image: ZeroIntensity]*ZeroIntensity* left a comment (python/cpython#131087) <#131087 (comment)> I've opted to not backport this because we're using thread state terms now. — Reply to this email directly, view it on GitHub <#131087 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BNITW56N5GH66FQNT6MXOHT2WAK6FAVCNFSM6AAAAABYY2QLM2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDONBYGM3TQNZSGE> . You are receiving this because you commented.Message ID: ***@***.***>

ZeroIntensity · 2025-05-05T10:23:21Z

@encukou I forgot about this one. Would you mind finishing up your review when you have some time?

vstinner

LGTM

Co-authored-by: Victor Stinner <vstinner@python.org>

miss-islington-app · 2025-05-17T08:58:44Z

Thanks @ZeroIntensity for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

…interpreters (pythonGH-131087) (cherry picked from commit af6b3b8) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Victor Stinner <vstinner@python.org>

encukou · 2025-05-17T08:58:52Z

Just did. Sorry for the delay!

bedevere-app · 2025-05-17T08:58:53Z

GH-134130 is a backport of this pull request to the 3.14 branch.

…ith subinterpreters (GH-131087) (GH-134130) Docs: C API: Improve documentation around non-Python threads with subinterpreters (GH-131087) (cherry picked from commit af6b3b8) Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Victor Stinner <vstinner@python.org>

…interpreters (pythonGH-131087) Co-authored-by: Victor Stinner <vstinner@python.org>

Document some examples and notes about non-Python threads with subint…
1b10658
…erpreters.

ZeroIntensity added skip issue topic-subinterpreters topic-C-API needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Mar 11, 2025

ZeroIntensity requested review from encukou, ericsnowcurrently and vstinner March 11, 2025 12:54

bedevere-appBot added docs Documentation in the Doc dir skip news awaiting review labels Mar 11, 2025

github-project-automationBot added this to Docs PRs Mar 11, 2025

github-project-automationBot moved this to Todo in Docs PRs Mar 11, 2025

ZeroIntensity mentioned this pull request Mar 17, 2025
Clarify the Purpose of the PyGILState API and Identify Better Alternatives #131267
Open

encukou reviewed Mar 18, 2025
View reviewed changes

Comment threadDoc/c-api/init.rst
Comment threadDoc/c-api/init.rst
Comment threadDoc/c-api/init.rst

Add clarification to 'only if'
1afcbb7

Merge branch 'main' into document-gilstate-subinterpreters
2e3d5d7

ZeroIntensity requested a review from encukou March 20, 2025 13:48

encukou reviewed Mar 24, 2025
View reviewed changes

Comment threadDoc/c-api/init.rst Outdated

Switch to thread state terms instead of the silly GIL
660aa77

ZeroIntensity removed needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Mar 24, 2025

vstinner reviewed May 5, 2025
View reviewed changes

Comment threadDoc/c-api/init.rst

vstinner approved these changes May 5, 2025
View reviewed changes

Comment threadDoc/c-api/init.rst Outdated

bedevere-appBot added awaiting merge and removed awaiting review labels May 5, 2025

Update init.rst
961d8b9
Co-authored-by: Victor Stinner <vstinner@python.org>

ZeroIntensity added the needs backport to 3.14 bugs and security fixes label May 8, 2025

encukou merged commit af6b3b8 into python:mainMay 17, 2025

bedevere-appBot removed the awaiting merge label May 17, 2025

github-project-automationBot moved this from Todo to Done in Docs PRs May 17, 2025

bedevere-appBot removed the needs backport to 3.14 bugs and security fixes label May 17, 2025

ZeroIntensity deleted the document-gilstate-subinterpreters branch May 17, 2025 11:30

Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025
Docs: C API: Improve documentation around non-Python threads with sub…
7e24409
…interpreters (pythonGH-131087) Co-authored-by: Victor Stinner <vstinner@python.org>

taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
Docs: C API: Improve documentation around non-Python threads with sub…
b79e789
…interpreters (pythonGH-131087) Co-authored-by: Victor Stinner <vstinner@python.org>

Navigation Menu

Uh oh!

Uh oh!

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

Docs: C API: Improve documentation around non-Python threads with subinterpreters#131087
encukou merged 5 commits into
python:mainfrom
ZeroIntensity:document-gilstate-subinterpreters

ZeroIntensity commented Mar 11, 2025•
edited
Loading

Uh oh!

sharktide commented Mar 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ZeroIntensity commented Mar 20, 2025

Uh oh!

Uh oh!

ZeroIntensity commented Mar 24, 2025

Uh oh!

sharktide commented Mar 24, 2025 via email

Uh oh!

ZeroIntensity commented May 5, 2025

Uh oh!

Uh oh!

vstinner left a comment

Uh oh!

Uh oh!

miss-islington-appBot commented May 17, 2025

Uh oh!

encukou commented May 17, 2025

Uh oh!

bedevere-appBot commented May 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Uh oh!

Conversation

ZeroIntensity commented Mar 11, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sharktide commented Mar 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ZeroIntensity commented Mar 20, 2025

Uh oh!

Uh oh!

ZeroIntensity commented Mar 24, 2025

Uh oh!

sharktide commented Mar 24, 2025 via email

Uh oh!

ZeroIntensity commented May 5, 2025

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-appBot commented May 17, 2025

Uh oh!

encukou commented May 17, 2025

Uh oh!

bedevere-appBot commented May 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ZeroIntensity commented Mar 11, 2025•
edited
Loading