gh-137026: Add an explainer guide for asyncio #137215
Conversation
This comment was marked as resolved.
This comment was marked as resolved.
- Start sentences on new lines to minimize disruption of diffs.
…Which concurrency do I want" section.
Yep! Was just taking a little break. All references to queue besides the one in that first analogy are now gone. |
|
@ZeroIntensity, @willingc: It should be noted, I just added a blurb about cpython/Doc/howto/a-conceptual-overview-of-asyncio.rst Lines 207 to 228 in 9d3828d |
| That example highlights how using only ``await coroutine`` could | ||
| unintentionally hog control from other tasks and effectively stall the event | ||
| loop. | ||
| :func:`asyncio.run` can help you detect such occurences with the ``debug=True`` |
There was a problem hiding this comment.
To clarify, the way I'd expect most developers to use this is not by modifying the code, but by running python in dev mode locally (-X dev or PYTHONDEVMODE=1). A link should take users to: https://docs.python.org/3/library/asyncio-dev.html#asyncio-debug-mode
There was a problem hiding this comment.
Added the link 👍
Hm. I agree but that's effectively a shortcut. Pedagogically, I think it's clearer to mention the debug=True flag.
There was a problem hiding this comment.
Hm. I agree but that's effectively a shortcut. Pedagogically, I think it's clearer to mention the
debug=Trueflag.
If you say so. I didn't even know that parameter existed and can't imagine ever using it. All I need to know as a user is that this feature exists and is enabled as part of dev mode..
| Once it pauses or completes, it returns control to the event loop. | ||
| The event loop will then select another job from its pool and invoke it. | ||
| You can *roughly* think of the collection of jobs as a queue: jobs are added and | ||
| then processed one at a time, generally (but not always) in order. |
There was a problem hiding this comment.
generally (but not always) in order.
I still find this bit awkward as it's again suggesting that order of execution is unpredictable. Can we say that the jobs are processed in the order that they were scheduled or something?
There was a problem hiding this comment.
Hm. If there's phrasing you have in mind, that the folks who are wary of the queue analogy would also be on board with, I'm open to it!
Co-authored-by: Kumar Aditya <kumaraditya@python.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Explainer guide for asyncio
gh-137026: HOWTO article for asyncio, and a reference to it from the main page of the asyncio docs.
Hi!
I've used Python's
asyncioa couple times now, but never really felt confident in my mental model of how it fundamentally works and therefore how I can best leverage it. The official docs provide good documentation for each specific function in the package, but, in my opinion, are missing a cohesive overview of the systems design and architecture. Something that could help the user understand the why and how behind the recommended patterns. And a way to help the user make informed decisions about which tool in the asyncio toolkit they ought to grab, or to recognize when asyncio is the entirely wrong toolkit. I thought I'd take a stab at filling that gap and contributing back to a community that's given so much!📚 Documentation preview 📚: https://cpython-previews--137215.org.readthedocs.build/en/137215/howto/a-conceptual-overview-of-asyncio.html