live thoughts as I read through that draft. i’m trying to play devils advocate and read this in all possible ways to come up with complaints. make sense?
you start out with “host computer” (and mentioning VM or container - but I don’t think we should touch the VM or container terms, they don’t matter). then later go on to say “for the small segments of time it is scheduled to execute its code on the CPU” in reference to threads - but we’ve never defined what a CPU is. a host computer is not a CPU as elliptically implied in the note. But we shouldn’t explain that, or explain the idea of time slicing. There really is no need to know if there are multiple CPU cores or how parallel execution happens, just that it must be assumed to. The key point to understand to me, even in that first note, is that threads must be assumed to run at the same time at potentially different non-synchronized rates, seeing a different view of overall changing global state
I’d also suggest using the term “host machine” instead of “host computer” as the word machine ties in better with “virtual machine” (which we don’t need to mention but will be familiar to many) - whereas what a “computer” at this point is thought of more as a physical object with a wide variety of sizes from a campus of warehouses down to an SoC.
You mention “OS” several times but should probably put it in the diagram between host machine and process.
“Every Python thread belongs to a single interpreter and runs using that shared state.”
could be misread to imply that each thread is its own interpreter using shared interpreter state. Perhaps word that as “Every Python thread that is part of the same interpreter shares Python state with all other threads in that interpreter …”
“For example, an OS thread might run code with a first interpreter and then with a second, each necessarily with its own Python thread.”
I’m really not sure how to parse this. it could be read to imply that there often are multiple interpreters and that they must have their own threads. or alternatively that threads imply multiple interpreters. I think it needs to be clear. “each necessarily with its own Python thread state tied to the specific interpreter” would make more sense to me.
“However, multiple Python threads can be associated with the same OS thread.”
I think this is confusing because in the most common case of there is only one interpreter this is not true. Any OS thread that executes within an interpreter has to have a single Python thread state matching that OS thread. There cannot be multiple running Python threads in one interpreter associated with the same OS thread.