Skip to content

gh-135944: Add a "Runtime Components" Section to the Execution Model Docs #135945

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
ericsnowcurrently merged 23 commits into from
Oct 2, 2025
Merged

gh-135944: Add a "Runtime Components" Section to the Execution Model Docs #135945

Changes from 1 commit
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
535c8b8
Add a "Runtime Components" section to the execution model docs.
ericsnowcurrently Jun 20, 2025
3f3d5cc
Fix a typo.
ericsnowcurrently Jun 27, 2025
b1d6ed7
Clarify about platform support for threads.
ericsnowcurrently Jun 27, 2025
aeca87a
Drop a comment.
ericsnowcurrently Jun 27, 2025
b12a02b
Identify what might be thread-specific state.
ericsnowcurrently Jun 27, 2025
17a2f34
Clarify about "interpreter".
ericsnowcurrently Jun 27, 2025
9ac4b4a
Clarify the relationship betwwen OS threads and Python threads and in…
ericsnowcurrently Jun 27, 2025
f7cb965
Clarify about the host.
ericsnowcurrently Jun 30, 2025
e71394c
Do not talk about distributed computing.
ericsnowcurrently Jun 30, 2025
8f454c4
Note the operating system in the diagram.
ericsnowcurrently Jun 30, 2025
cd0200c
Avoid talking about how threads are scheduled.
ericsnowcurrently Jun 30, 2025
9ccc743
Be more specific about the "pain" of threads.
ericsnowcurrently Jun 30, 2025
4dce0fc
Clarify about the relationship between OS threads, Python threads, an…
ericsnowcurrently Jun 30, 2025
bf1f1a2
Various refactors, incl. drop mention of "OS".
ericsnowcurrently Sep 25, 2025
b58a95c
Drop "call into Python" discussion.
ericsnowcurrently Sep 25, 2025
f05848c
Fix literal block.
ericsnowcurrently Sep 29, 2025
6304a23
Fix Python layers.
ericsnowcurrently Sep 29, 2025
e9c946f
Fix an ambiguous sentance.
ericsnowcurrently Sep 29, 2025
8de5e0a
Fix an ambiguous commit hash.
ericsnowcurrently Sep 29, 2025
b81dbd2
Clarify about thread state independence.
ericsnowcurrently Sep 29, 2025
cd144de
Clarify about multiple thread states per host thread.
ericsnowcurrently Sep 29, 2025
582b924
Clarify about asyncio.
ericsnowcurrently Sep 30, 2025
78e4bbc
Add a link to the commit on github.
ericsnowcurrently Sep 30, 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
Clarify the relationship betwwen OS threads and Python threads and in… 
…terpreters.
  • Loading branch information
@ericsnowcurrently
ericsnowcurrently committed Jun 27, 2025
commit 9ac4b4a00345543504609687f570629745a58853
20 changes: 12 additions & 8 deletions Doc/reference/executionmodel.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -446,20 +446,24 @@ exception and the Python call stack.
In between the global runtime and the thread(s) lies the interpreter.
It completely encapsulates all of the non-process-global runtime state
that the interpreter's Python threads share. For example, all its
threads share :data:`sys.modules`. When a Python thread is created,
it belongs to an interpreter, and likewise when an OS thread is
otherwise associated with Python.
threads share :data:`sys.modules`. Every Python thread belongs to a
single interpreter and runs using that shared state. The initial
Comment thread
ericsnowcurrently marked this conversation as resolved.
Outdated
interpreter is known as the "main" interpreter, and the initial thread,
where the runtime was initialized, is known as the "main" thread.

.. note::

The interpreter here is not the same as the "bytecode interpreter",
which is what runs in each thread, executing compiled Python code.

If the runtime supports using multiple interpreters then each OS thread
will have at most one Python thread for each interpreter. However,
only one is active in the OS thread at a time. Switching between
interpreters means changing the active Python thread.
The initial interpreter is known as the "main" interpreter.
Every Python thread is associated with a single OS thread, which is
where it runs. However, multiple Python threads can be associated with
the same OS thread. For example, an OS thread might run code with a
Comment thread
ericsnowcurrently marked this conversation as resolved.
Outdated
first interpreter and then with a second, each necessarily with its own
Python thread. Still, regardless of how many are *associated* with
an OS thread, only one Python thread can be actively *running* in
an OS thread at a time. Switching between interpreters means
changing the active Python thread.
Comment thread
ericsnowcurrently marked this conversation as resolved.
Outdated

Once a program is running, new Python threads can be created using the
:mod:`threading` module (on platforms and Python implementations that
Expand Down