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

ericsnowcurrently · 2025-06-25T15:45:43Z

The section provides a brief overview of the Python runtime's execution environment.

This is meant to be implementation agnostic, If that doesn't hold true then we should take a different approach.

Issue: Add a Section to the Language Reference About Runtime Components #135944

📚 Documentation preview 📚: https://cpython-previews--135945.org.readthedocs.build/

ZeroIntensity · 2025-06-25T15:57:40Z

Doc/reference/executionmodel.rst

@@ -398,6 +398,75 @@ See also the description of the :keyword:`try` statement in section :ref:`try`
 and :keyword:`raise` statement in section :ref:`raise`.


+.. _execcomponents:
+
+Runtime Components


I think it would be a good idea to mention that this is CPython specific. Other implementations are allowed to have different runtime models.

This is meant to be implementation agnostic

Oh, oops, didn't see this. Some parts are CPython specific here, though.

I'm trying to avoid any CPython-specific notions here. Do you have an example of another runtime model?

No, I'm not familiar with how any other implementations work, this is coming solely off a bit of speculation on my part. My concern is that a thread is inherently CPython-specific, because some Python implementations exist in areas that don't have access to OS threads, such as Brython for JS, and probably MicroPython/CircuitPython for some microcontrollers.

I do think that this is a great section to have for subinterpreters, I just think it'd be better to keep some parts of it CPython specific. Does that make sense?

From a conceptual standpoint, which is the level of this text, threads are not implementation-specific (or platform-specific): the Python runtime always deals with at least the one thread in which it was started. Not all platforms and implementations support multiple threads, but that's a different matter. I'll add a sentence clarifying that point.

Ok, I think I can get behind that. Thanks!

On the question of implementations that do not have access to OS threads, unless they are unable to create Thread objects, I think this is covered by the possibility of multiple Python threads may be mapped to the single OS thread available. I'm assuming this is multiple Python threads in one interpreter, but interested to be reassured about the multiplicity of the relationships in this data model. I'm reading "OS thread" as "JVM Thread" for my purposes. It's not necessarily the same, but I don't think we can/should peek behind that particular abstraction.

Doc/reference/executionmodel.rst

neonene · 2025-06-26T10:01:01Z

Doc/reference/executionmodel.rst

+         interpreter
+           Python thread (runs bytecode)
+
+when a Python program starts, it looks exactly like that, with one


capitalization: When

neonene · 2025-06-26T10:01:10Z

Doc/reference/executionmodel.rst

+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.


Probably I'm misreading:

Suggested change

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.

If the runtime supports using multiple interpreters then each OS thread

will have at least one Python thread for each interpreter. However,

only one is active in the OS thread at a time. Switching between

interpreters in the current OS thread means changing the active Python thread.

It's "at most" because there may be zero or one Python thread per thread per interpreter. However, that isn't strictly true, since you can create as many thread states as you want. Only one can be active at a time for a give thread and each one is strictly bound to a single thread. I'll tweak the wording. Thanks for pointing this out.

ericsnowcurrently · 2025-06-27T17:55:52Z

FWIW, I'm going to open a DPO thread about this addition before merging, to make sure there's sufficient visibility.

…terpreters.

ericsnowcurrently · 2025-06-27T20:23:08Z

https://discuss.python.org/t/96922

jeff5

Very much support the idea of clearly explaining this. I hope the comments are not too ignorant to be useful.

jeff5 · 2025-06-30T13:08:51Z

Doc/reference/executionmodel.rst

+While a program always starts with exactly one of each of those, it may
+grow to include multiple of each.  Hosts and processes are isolated and
+independent from one another.  However, threads are not.
+


This falls a little oddly: "multiples of each". Threads, sure. But to say that a (Python) program could grow to include multiple hosts or processes would take a more extended idea of "program" than I think the execution model seeks to address. Wouldn't it?

Good point. I'll narrow that.

jeff5 · 2025-06-30T13:18:08Z

Doc/reference/executionmodel.rst

+   The way they share resources is exactly what can make threads a pain:
+   two threads running at the same arbitrary time on different CPU cores
+   can accidentally interfere with each other's use of some shared data.
+


This sounds a bit like the risk of accidents is unavoidable. Though I take your point, some science is available, so I offer: "The care needed to co-ordinate access to intentionally shared data, when two or more threads could be running, is exactly what makes threads a painful way to exploit the potential concurrence of multiple CPUs."

Arguably, the risk of accidents with threads is unavoidable. 😄 That said, I'll clarify similarly to what you've suggested.

jeff5 · 2025-06-30T13:21:35Z

Doc/reference/executionmodel.rst

+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`.  Every Python thread belongs to a
+single interpreter and runs using that shared state.  The initial


I think your point, providing an important example of this encapsulation, is:
all its threads share :data:sys.modules, but each interpreter will manage its own :data:sys.modules independently.

jeff5 · 2025-06-30T13:34:25Z

Doc/reference/executionmodel.rst

+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.


"... for that particular OS thread."

Actually, the use of two terms may be why I feel like adding words. If "active" and "running" mean the same thing, I would say choose one. If there is an important distinction, it's not clear. Should we maybe refer to the (one) active Python thread, in each interpreter, for a given OS thread. That may or may not be running as far as the OS is concerned (if that even matters to us).

Yeah, this is the part where it was hardest to get the wording right. I'll clarify.

Agree. Looking back, I realise the relevant state of an OS thread is "runnable", rather than "running". We don't care whether the OS thread is actually running, only whether it might make progress "without asking" or is properly blocked. But I struggle to understand how this is in CPython, relates to thread state, and what part of that is implementation-neutral.

fixed (hopefullly) -- let me know what you think of the updated text

jeff5 · 2025-06-30T13:48:42Z

Doc/reference/executionmodel.rst

+
+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


We haven't precluded, but haven't expicitly mentioned, one OS thread associated with multiple Python threads in the same interepreter.

There's no prohibition. You're right that it's worth pointing out explicitly.

jeff5 · 2025-06-30T13:54:35Z

Doc/reference/executionmodel.rst

@@ -398,6 +398,75 @@ See also the description of the :keyword:`try` statement in section :ref:`try`
 and :keyword:`raise` statement in section :ref:`raise`.


+.. _execcomponents:
+
+Runtime Components


On the question of implementations that do not have access to OS threads, unless they are unable to create Thread objects, I think this is covered by the possibility of multiple Python threads may be mapped to the single OS thread available. I'm assuming this is multiple Python threads in one interpreter, but interested to be reassured about the multiplicity of the relationships in this data model. I'm reading "OS thread" as "JVM Thread" for my purposes. It's not necessarily the same, but I don't think we can/should peek behind that particular abstraction.

…d interpreters.

ericsnowcurrently · 2025-06-30T22:38:41Z

@gpshead, I've updated the PR to address your comments at https://discuss.python.org/t/proposal-add-text-to-the-language-reference-about-runtime-components/96922/2, Thanks!

Add a "Runtime Components" section to the execution model docs.

535c8b8

ericsnowcurrently requested review from willingc and AA-Turner as code owners June 25, 2025 15:45

ericsnowcurrently added skip news needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jun 25, 2025

bedevere-app bot added awaiting core review docs Documentation in the Doc dir labels Jun 25, 2025

github-project-automation bot added this to Docs PRs Jun 25, 2025

github-project-automation bot moved this to Todo in Docs PRs Jun 25, 2025

bedevere-app bot mentioned this pull request Jun 25, 2025

Add a Section to the Language Reference About Runtime Components #135944

Open

ZeroIntensity reviewed Jun 25, 2025

View reviewed changes

neonene reviewed Jun 26, 2025

View reviewed changes

Fix a typo.

3f3d5cc

ericsnowcurrently added 5 commits June 27, 2025 11:58

Clarify about platform support for threads.

b1d6ed7

Drop a comment.

aeca87a

Identify what might be thread-specific state.

b12a02b

Clarify about "interpreter".

17a2f34

Clarify the relationship betwwen OS threads and Python threads and in…

9ac4b4a

…terpreters.

jeff5 reviewed Jun 30, 2025

View reviewed changes

ericsnowcurrently added 6 commits June 30, 2025 11:23

Clarify about the host.

f7cb965

Do not talk about distributed computing.

e71394c

Note the operating system in the diagram.

8f454c4

Avoid talking about how threads are scheduled.

cd0200c

Be more specific about the "pain" of threads.

9ccc743

Clarify about the relationship between OS threads, Python threads, an…

4dce0fc

…d interpreters.

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

ericsnowcurrently commented Jun 25, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericsnowcurrently commented Jun 27, 2025

Uh oh!

ericsnowcurrently commented Jun 27, 2025

Uh oh!

jeff5 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericsnowcurrently commented Jun 30, 2025

Uh oh!

Uh oh!

ericsnowcurrently commented Jun 25, 2025 •

edited by github-actions bot

Loading