Issues in asyncio documentation section "A homemade asyncio.sleep"

[padoremu]

Documentation

Link to section:
https://docs.python.org/3/howto/a-conceptual-overview-of-asyncio.html#a-homemade-asyncio-sleep

From my perspective, there are two issues in this section:

1. Creating a task for the sleep call in main (await asyncio.create_task(async_sleep(3))) hides if the implementation actually cedes control to the event loop as desired or if it blocks it - an implementation using time.sleep(seconds) would also behave sane here. Therefore, I think it should be changed to await async_sleep(3).
2. The implementation is said to mimick asyncio.sleep(), which can make readers think that this could actually be a usable replacement that behaves similarly. However, in one crucial aspect it behaves the opposite way: It causes 100% CPU usage on one core due to the busy waiting approach, which is opposed to how a sleep should behave. Two options I see:

• Add something like: "Note: This implementation uses busy waiting and will consume 100% CPU on one core, unlike the real asyncio.sleep(). This implementation is purely meant for educational purposes to demonstrate futures and event loop interaction."
• Add a synchronous time.sleep(0.001) or such right before await YieldToEventLoop() (in both example implementations) and explain (trade-off, sub-optimal workaround, will cause undesired CPU usage but significantly less than without).

[picnixz]

cc @anordin95

[gvanrossum]

I'm unclear on what that section is trying to teach.

The proper way to implement async sleep is only a few lines using the low-level (event loop) API:

async def async_sleep(dt: int|float) -> None:
    loop = asyncio.get_running_loop()
    fut = loop.create_future()
    loop.call_later(dt, fut.set_result, None)
    await fut

Examples using busy-wait (even if interruptible) are anti-patterns in asyncio.

[anordin95]

@padoremu Hi. Thanks for the detailed writeup!

1. Ah, good callout! Not only that, but it also may begin the sleep timer later than expected, since other Tasks in the event loop will be tended to before async_sleep(3).
2. Mhm, that's a fair point. I recall I was concerned with the pedagogical tradeoff of implementing an asyncio.sleep and using time.sleep within it. For folks newer to programming, I was concerned the two different sleeps may be confusing. I lean towards your first suggestion, adding a note to clarify the busy-wait behavior.

@gvanrossum, hi, per the broader article's first sentence, the section is presumably trying to teach: "[a] sturdy mental model of how asyncio fundamentally works, helping you understand the how and why behind the recommended patterns.".
The implementation you provide is great! But, I don't think it helps someone build a strong understanding of how asyncio works. For example, loop.call_later leverages loop.call_at, which adds to the loop's queue of scheduled tasks, and the task will eventually be called in the loop._run_once method where scheduled tasks are checked for readiness (i.e. enough time elapsed). I think that's more convoluted and ultimately less insightful.
I do hear you regarding the article potentially leading folks astray regarding busy-waits. My response above (2.) applies here too.

[padoremu]

I agree with @anordin95 that the purpose of the example in that section is to support teaching fundamental asyncio concepts and for that it does a fine job I find. Personally, I also tend towards my first suggestion with the comment.

From a pure implementation point of view, the one shown by @gvanrossum is great of course - it is essentially how asyncio.sleep is implemented.