gh-138072: Small clarifications and phrasing improvements to asyncio HOWTO #138073
Conversation
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
| :mod:`!asyncio` automatically associates tasks with the event loop for you. | ||
| Typically there's only one event loop, so that's quite straightforward. | ||
| It's uncommon, but some applications use multithreading and :mod:`!asyncio` | ||
| together, where there's one event loop per thread, stored in thread-local |
There was a problem hiding this comment.
"stored in thread-local" is unnecesary implemenetation detail for the reader, just per thread seems sufficient.
There was a problem hiding this comment.
See discussion here: #138073 (comment)
There was a problem hiding this comment.
I'd also be OK with just "per thread". But, I don't totally understand the rationale to clarify thread-locality here -- what was wrong with the original wording?
There was a problem hiding this comment.
This paragraph states asyncio automatically associates tasks with the event loop so you, the user, don't need to specify the loop in the asyncio.create_task constructor (nor are you even allowed to). And with "per thread", it implies there can be multiple event loops (via multithreading) in the same memory space.
I think it's quite natural to then wonder how tasks will be associated with event loops when there are multiple event loops to choose from. And how you, the user, could manage which loop a task is assigned to. I see that as an easy way for the reader to get confused. The point of this article is to be explanatory.
While, yes, it is an implementation detail, it's not some arcane, fragile aspect. It's a fundamental design pattern exposed by the OS. And, it appears this usage of thread-local hasn't changed in the 12 years that asyncio has been around.
| @@ -251,6 +253,10 @@ different ways:: | |||
| In a crucial way, the behavior of ``await`` depends on the type of object | |||
| being awaited. | |||
|
|
|||
| ^^^^^^^^^^ | |||
| await task | |||
There was a problem hiding this comment.
| await task | |
| Awaiting Tasks |
There was a problem hiding this comment.
I prefer the original for two reasons.
The titles come from the references made in the broader await section intro.
And they fit more naturally in the broader table of contents:
| @@ -282,6 +288,10 @@ This is a basic, yet reliable mental model. | |||
| In practice, the control handoffs are slightly more complex, but not by much. | |||
| In part 2, we'll walk through the details that make this possible. | |||
|
|
|||
| ^^^^^^^^^^^^^^^ | |||
| await coroutine | |||
There was a problem hiding this comment.
| await coroutine | |
| Awaiting Coroutines |
📚 Documentation preview 📚: https://cpython-previews--138073.org.readthedocs.build/