Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

gh-127989: C API: Refer to attached thread states instead of the GIL #127990

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.

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 76 commits into from
Mar 20, 2025
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
76 commits
Select commit Hold shift + click to select a range
ad7ee2d
Document the term 'thread state.'
ZeroIntensity Dec 14, 2024
bea045a
Change term for PyDict_GetItem
ZeroIntensity Dec 14, 2024
e286ba5
Change term for PyErr_Occurred
ZeroIntensity Dec 14, 2024
6006b22
Change term for PyErr_SetInterrupt
ZeroIntensity Dec 14, 2024
8dc3928
Change term for PyErr_SetInterruptEx
ZeroIntensity Dec 14, 2024
f46ca3d
Change term for PyConfig_Get
ZeroIntensity Dec 14, 2024
555a03c
Change term for PyConfig_Names
ZeroIntensity Dec 14, 2024
ddb98cd
Change term for PyConfig_Set
ZeroIntensity Dec 14, 2024
5d423f8
Change term for PyUnstable_AtExit
ZeroIntensity Dec 14, 2024
d2d2f67
Change term for Py_Initialize note
ZeroIntensity Dec 14, 2024
aa9c4c6
Change term for PyInterpreterState_Get
ZeroIntensity Dec 14, 2024
c05be67
Change term for PyInterpreterState_GetID
ZeroIntensity Dec 14, 2024
3a69922
Change term for PyThreadState_SetAsyncEx
ZeroIntensity Dec 14, 2024
3336ad7
Change term for Py_NewInterpreterFromConfig
ZeroIntensity Dec 14, 2024
3991681
Change term for Py_FinalizeEx
ZeroIntensity Dec 14, 2024
6d397eb
Change term for Py_AddPendingCall
ZeroIntensity Dec 14, 2024
3b7b3ff
Change term for PyEval_SetProfile
ZeroIntensity Dec 14, 2024
5358d14
Change term for PyEval_SetProfileAllThreads
ZeroIntensity Dec 14, 2024
093ba05
Change term for PyEval_SetTrace
ZeroIntensity Dec 14, 2024
11582fa
Change term for PyEval_SetTraceAllThreads
ZeroIntensity Dec 14, 2024
3d55d2d
Change term for PyRefTracer_SetTracer
ZeroIntensity Dec 14, 2024
2785c1d
Change term for PyRefTracer_GetTracer
ZeroIntensity Dec 14, 2024
6d80b02
Change term for PyMutex_Lock
ZeroIntensity Dec 14, 2024
94e046b
Change term for allocator domains
ZeroIntensity Dec 14, 2024
713beb2
Change term for raw memory interface
ZeroIntensity Dec 14, 2024
2140bde
Change term for memory interface
ZeroIntensity Dec 14, 2024
f608211
Change term for object allocators
ZeroIntensity Dec 14, 2024
d619387
Change term for PyMem_SetAllocator
ZeroIntensity Dec 14, 2024
e7828ed
Change term for PyMem_SetAllocator (again)
ZeroIntensity Dec 14, 2024
6b33565
Change term for debug hooks
ZeroIntensity Dec 14, 2024
6230177
Change term for debug hooks (again)
ZeroIntensity Dec 14, 2024
f74832a
Change term for PyState*
ZeroIntensity Dec 14, 2024
7161fc0
Change term for various things
ZeroIntensity Dec 14, 2024
d58b74f
Change term for clock functions
ZeroIntensity Dec 14, 2024
a761c4a
Change term for raw clock functions
ZeroIntensity Dec 14, 2024
de122f5
Change term for tp_dealloc warning
ZeroIntensity Dec 14, 2024
0b0176b
Change term for the types tutorial
ZeroIntensity Dec 14, 2024
c15f5c4
Add more information about thread states.
ZeroIntensity Dec 14, 2024
0130b20
Change terms for 'cautions regarding runtime finalization'
ZeroIntensity Dec 14, 2024
a1e47b7
Simplify PyEval_SaveThread and PyEval_RestoreThread
ZeroIntensity Dec 14, 2024
0173c46
Some more terminology fixups.
ZeroIntensity Dec 14, 2024
166d970
Fix Sphinx build errors.
ZeroIntensity Dec 14, 2024
adae494
Change some usage of the term 'global interpreter lock'
ZeroIntensity Dec 14, 2024
a70ab11
Add some more terms for disambiguation.
ZeroIntensity Dec 14, 2024
8584c86
Change usage of some terms.
ZeroIntensity Dec 14, 2024
48b145a
Play around with terminology.
ZeroIntensity Dec 14, 2024
8ce3d7d
Various terminology changes.
ZeroIntensity Dec 14, 2024
e5f1d18
Change the glossary definition a little bit.
ZeroIntensity Dec 14, 2024
905ca5b
Change some phrasing.
ZeroIntensity Dec 14, 2024
f2826c4
Fix some usage of terms.
ZeroIntensity Dec 14, 2024
5c44391
Change some usage of 'global interpreter lock'
ZeroIntensity Dec 15, 2024
7d5877f
Fix pre-commit lint.
ZeroIntensity Dec 15, 2024
283fc92
Delete redundant file
ZeroIntensity Dec 16, 2024
a7488ab
Revert "Delete redundant file"
ZeroIntensity Dec 16, 2024
4c532b6
Remove accidental find-and-replace change.
ZeroIntensity Dec 16, 2024
352acc5
Switch to a reference
ZeroIntensity Dec 16, 2024
ed550bc
Use a less wordy phrase for detaching.
ZeroIntensity Dec 16, 2024
d7cf403
Fix a typo in PyInterpreterState_Get
ZeroIntensity Dec 16, 2024
f61a6da
Change some wording in PyEval_SaveThread and PyEval_RestoreThread
ZeroIntensity Dec 16, 2024
36af941
Change wording for PyThreadState_Swap
ZeroIntensity Dec 16, 2024
0b23daa
Make glossary terms more clear.
ZeroIntensity Dec 16, 2024
163b0b8
Change up wording for 'attached thread state'
ZeroIntensity Dec 16, 2024
3b2bed8
Clarify that the C API is what needs a thread state.
ZeroIntensity Dec 16, 2024
80ae46b
Update Doc/glossary.rst
ZeroIntensity Dec 17, 2024
3dee63f
Update Doc/glossary.rst
ZeroIntensity Dec 17, 2024
9ed3a0b
Drop the phrase 'current thread state' and only use 'attached thread …
ZeroIntensity Feb 12, 2025
b3cbbf8
Add extra note about free-threading.
ZeroIntensity Feb 12, 2025
1c37d59
Add a seealso.
ZeroIntensity Feb 12, 2025
32a4937
Merge from main.
ZeroIntensity Feb 12, 2025
2fba67c
Fix weird merge artifact.
ZeroIntensity Feb 12, 2025
a0dc12c
Merge branch 'main' into clarify-gil-tstate
ZeroIntensity Feb 27, 2025
94619f6
Change term for new PyConfig* APIs
ZeroIntensity Feb 27, 2025
e6f1f28
Change term for PyUnstable_InterpreterState_GetMainModule
ZeroIntensity Feb 27, 2025
828d24b
Change term for Py_fopen
ZeroIntensity Feb 27, 2025
ace174f
Merge branch 'main' into clarify-gil-tstate
encukou Mar 19, 2025
788d735
Change artifact from 'runtime context' to 'thread state'
ZeroIntensity Mar 20, 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
Change some phrasing.
  • Loading branch information
ZeroIntensity committed Dec 14, 2024
commit 905ca5bf62c6ba3bd80d499e4f5150034562b35b
2 changes: 1 addition & 1 deletion 2 Doc/c-api/init.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1411,7 +1411,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.

.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)

Destroy a :term:`thread state`` object. *tstate* should not
Destroy a :term:`thread state` object. *tstate* should not
be :term:`attached <attached thread state>` to any thread.
*tstate* must have been reset with a previous call to
:c:func:`PyThreadState_Clear`.
Expand Down
19 changes: 13 additions & 6 deletions 19 Doc/glossary.rst
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few points to consider, which are reflected in my other comments:

  • current does not imply attached, but attached does implies current
  • the glossary probably isn't the best place for C-API details
  • "runtime context" or "execution context" might be a clearer term for users than "thread state"

The only tricky part is that we already talk about "contexts" relative to asyncio.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll commit the suggestions tomorrow when I'm available to do a full find-and-replace so I don't blow up CI in the meantime.

For the per-thread thread state pointer (what a mouthful!), I'm happy with something like "runtime context," because there was no prior term for it, but I think we do want to keep the term "thread state." Thread states are documented, and users like to read the source code to understand some C functions--seeing _PyThreadState_GET and "thread state" in the documentation makes things more clear. That, and "context" doesn't convey the fact that it's a thread-local too well, which is important.

the glossary probably isn't the best place for C-API details

Hmm, we do have "borrowed reference" and "strong reference" in there; where else should "thread state" point to?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"runtime context" or "execution context" might be a clearer term for users than "thread state"

I like "thread state" :-)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for sticking with thread state.

Between contextvars and context managers, and just the general idea of "context of execution", "context" is seriously overloaded already.

"thread state" isn't completely unambiguous (it could theoretically take on the holistic meaning of "all state associated with the current thread, including the execution stack and all thread local variables"), but the context(!) of use should help avoid that misinterpretation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Runtime context" in particular is problematic, since the execution model is set up with the hierarchy of:

  • there is one runtime, which may be serially finalized and reinitialized, but you can never have more than one at a time
  • the runtime will host at least one interpreter, but may host more
  • each interpreter will have at least one thread state, but may have more
  • for an OS thread to execute Python code, it must be associated with a Python thread state (which also indirectly determines which interpreter it is associated with)

Original file line number Diff line number Diff line change
Expand Up @@ -137,10 +137,12 @@ Glossary
A :term:`thread state` that is :term:`active <current thread state>`
for the current thread. If no thread state is attached, then the
:term:`current thread state` is ``NULL``. Attempting to call Python
without an attached thread state will generally result in a fatal error.
without an attached thread state will result in a fatal error.

A thread state can be attached and detached explicitly by the user, or
implicitly by the interpreter.
implicitly by the interpreter in between calls. For example, an attached
thread state is detached upon entering a :c:macro:`Py_BEGIN_ALLOW_THREADS`
block, and then re-attached when :c:macro:`Py_END_ALLOW_THREADS` is reached.

On most builds of Python, having an attached thread state means that the
caller holds the :term:`GIL` for the current interpreter.
Expand Down Expand Up @@ -348,10 +350,15 @@ Glossary

current thread state

The :c:data:`PyThreadState` pointer to a :term:`thread state` for the current thread.
The per-thread pointer might be ``NULL``, in which case Python code should not
get executed. If the current thread state is non-``NULL``, then the :term:`thread state`
that it points to is considered to be :term:`attached <attached thread state>`.
A per-thread :c:data:`PyThreadState` pointer for the current thread.
The pointer might be ``NULL``, in which case Python code should not
ZeroIntensity marked this conversation as resolved.
Show resolved Hide resolved
get executed.

If the current thread state is non-``NULL``, then the :term:`thread state`
that it points to is considered to be :term:`attached <attached thread state>`.

The per-thread pointer can be acquired via :c:func:`PyThreadState_Get` or
:c:func:`PyThreadState_GetUnchecked` if it might be ``NULL``.

decorator
A function returning another function, usually applied as a function
Expand Down
Morty Proxy This is a proxified and sanitized view of the page, visit original site.