Hi @ambv, If you have the time to review this PR, I think your perspective would be helpful. You did a great job on the 8-part asyncio youtube playlist on clearly explaining an event loop. I'm hoping your fresh eyes will help us find wording that strikes the right tone for explanation while also being technically accurate.

This is based on the concept of lies-to-children ("a simplified, and often technically incorrect, explanation of technical or complex subjects employed as a teaching method"). This tutorial is targeted towards beginners, so it should be totally OK to use some information that's technically incorrect in the pursuit of initial comprehension.

Thanks @ZeroIntensity and @anordin95. HOWTO guides are not strictly targeted to beginners rather they are a deeper explanation of something. The name HOWTO comes from early Linux days as a deep dive into a particular area.

OK, we are down to one key decision: the best mental model for an event loop. We've been discussing a) the queue and b) the execution of scheduled work.

Event loops run asynchronous tasks and callbacks, perform network IO operations, and run subprocesses.

From the event loop docs, the above defines work run by an event loop. I'm going to suggest that instead of sticking with "queue" which doesn't sit well with multiple asyncio maintainers that we explore some other terms: "to do list", "work checklist", "collection of work".

Working from the conductor metaphor:

Like a symphony conductor, the event loop orchestrates multiple performers (tasks). It knows when each section should play, pauses some while others perform, and coordinates the overall harmony of concurrent operations.

OK, we are down to one key decision: the best mental model for an event loop. We've been discussing a) the queue and b) the execution of scheduled work.

Like a symphony conductor, the event loop orchestrates multiple performers (tasks). It knows when each section should play, pauses some while others perform, and coordinates the overall harmony of concurrent operations.

This is a beautiful idea! But, I'm a bit wary of using it, since in a symphony many sections play truly concurrently. The trumpets, the drums & the flutes could all be going at once.

I reworked the event loop paragraph a decent bit (see below). The idea of a queue is mentioned only once now and is explicitly called out as a rough analogy twice in the sentence . Otherwise, I refer to the event loop's jobs with a variety of similar but different terms to help reinforce and contextualize the idea. Alongside this change, my idea also entails removing any other references to a queue in the broader article.

In more technical terms, the event loop contains a collection of jobs to be run. Some jobs are added directly by you, and some indirectly by asyncio. The event loop takes a job from its backlog of work and invokes it (or "gives it control"), similar to calling a function, and then that job runs. 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. This process repeats indefinitely with the event loop cycling endlessly onwards. If there are no more jobs pending execution, the event loop is smart enough to rest and avoid needlessly wasting CPU cycles, and will come back when there's more work to be done.

Cool @anordin95! I like the last commit you pushed. 🎉 Can we continue throughout the doc to deemphasize queue?

Can we continue throughout the doc to deemphasize queue?

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 Task garbage collection at the end of the "tasks" section. I was initially on the fence but I think it's important, useful context to include.