The event loop: one thread, one queue, and six steps on repeat

One person behind a counter

Picture a service counter. One person behind it. In front of them is a stack of slips — the jobs that are due. Next to them, an alarm clock that can be set for any time. And a hatch through which new requests arrive.

They have exactly one rule, and it matters more than everything else:

Took the stack — do everything that was in it at the moment you took it. Slips added while you worked go into the next round.

When the stack is empty and the alarm has not rung, the person sleeps. Not staring at the wall — actually asleep, waking either to the alarm or to something coming through the hatch.

That is the whole event loop. Everything else is detail.

What it is made of

Open the sources and it turns out to be literally three things:

• the stack — the queue of jobs due right now;
• the alarm clock — a set of timers sorted by time, nearest one on top;
• the hatch — the thing that watches network connections and knows how to sleep while nothing is happening.

There is no "scheduler" in there deciding who gets to work next. There is a queue and the rule "do everything that was in it".

Switch to the "What it is made of" tab — those three parts are drawn there with their real names and arrows for what ends up where.

What await does

await is not "wait here". It is "I need a result; if it is not ready yet, put me to sleep and go do something else".

async def fetch_data():
    response = await request_the_server()   # <- here the function goes to sleep
    return response.text                    # <- and comes back here when the answer arrives

A second may pass between those two lines, and for that whole second the person behind the counter is dealing with other jobs. The function is not "hanging" — it was simply set aside, and once the result appeared it was put back into the stack.

An important detail: if the result is already there, nobody goes anywhere. The function just continues. That is why three nested awaits in a row, where nothing actually waits, cost exactly as much as an empty program — and that has been measured.

Why one time.sleep breaks everything

Now the main rule of async code makes sense too.

async def bad():
    time.sleep(0.1)          # the person behind the counter froze for 100 ms
 
async def good():
    await asyncio.sleep(0.1) # the person set the alarm and moved on to others

The difference is not that the first is "slower". The difference is that the first occupies the only worker, and everything else simply does not happen.

Measured on CPython 3.13.7 — fifty tasks, each busy for 100 ms:

Fifty times a hundred milliseconds added up to five seconds, because all fifty tasks landed in one stack and were done back to back, one after another. In the second case all fifty alarm clocks were ticking at the same time.

The second measurement on that same tab is more vivid. A background task asks to be woken every 10 milliseconds — over a second it should tick about a hundred times.

• The worker blocks: it ticked 4 times.
• The worker yields: it ticked 99 times.

The worker in the first row did give up control after every chunk — it only blocks inside one. It did not help: one yield per hundred milliseconds of work is far too little.

What to do when blocking is unavoidable

Sometimes you have to call a library that knows nothing about async. There is a ready-made way — hand it to a separate thread:

result = await asyncio.to_thread(slow_function, argument)

The person behind the counter hands the job to a neighbour in the back room and returns to their own stack. When the neighbour finishes, the result goes into that stack as an ordinary slip. This is the one correct answer to "but I need to call something blocking".

Three things worth remembering

There is one worker. Everything else is a consequence.

await is not a pause, it is a marker saying "you may set me aside here". If there is nothing to set aside, nothing happens.

Slow is not the task that waits a long time, but the task that holds the worker a long time. A task that spends ten seconds waiting for the network bothers nobody. A task that spends a hundred milliseconds computing bothers everyone.

Why bother?

Everybody writes async Python; few can say what happens between await and the line after it. That usually does no harm — until one of three things happens: a service inexplicably freezes for a second, asyncio.sleep(0.01) somehow sleeps for 30 ms, or adding one more task ruins the responsiveness of the whole application.

All three come from one mechanism, and it fits in a single eighty-line function. This article takes that function apart in full — and checks every claim by measuring it on a live interpreter.

The model to hold in your head

Picture one person behind a counter. In front of them is a stack of slips — the queue of work that is ready to be done. Next to them is an alarm clock that can be set for any time. And there is a hatch through which new requests are pushed.

They work by a single rule: take the stack, do everything that was in it at the moment they picked it up, and only then look at the clock and the hatch. Slips added while they worked go into the next round.

While the stack is empty and the alarm has not rung, they sleep — not "spin idle", but genuinely sleep, waking either to the alarm or to something arriving through the hatch.

Everything else in this article sharpens that picture until it can be checked against code. One detail matters right away: there is one person. While they are busy with one slip, they look neither at the clock nor at the hatch. Not out of stubbornness — there is simply only one of them.

What the loop is made of

Before taking apart what the loop does, it is worth seeing what it is built from. It is literally an object with three containers, and everything that happens in an async program is work being moved between them.

# base_events.py, BaseEventLoop.__init__ — tag v3.13.7
class BaseEventLoop(events.AbstractEventLoop):
    def __init__(self):                                    # :419
        self._timer_cancelled_count = 0                    # :420
        self._ready = collections.deque()                  # :423
        self._scheduled = []                               # :424
        self._clock_resolution = time.get_clock_info('monotonic').resolution  # :430

# selector_events.py, BaseSelectorEventLoop.__init__ — same tag
        if selector is None:
            selector = selectors.DefaultSelector()         # :63
        self._selector = selector                          # :65

Five lines, and that is the whole inventory.

_ready — the queue of what is due right now. A plain deque. It is the single entrance to execution: a fired timer, a readable socket, a call_soon — all of them land here first and are only then run.

_scheduled — the heap of timers, ordered by deadline (an ordinary list, but worked through heapq, so the nearest deadline is always at the head). Everything asked for "later" goes here: call_later, call_at, and the insides of asyncio.sleep.

_selector — a wrapper around epoll (or kqueue, or select, depending on the system). The only thing that knows about sockets, and the only place where the process actually sleeps.

Above these three sits the layer of tasks and futures, and below them is exactly one function that calls anything. And note that the loop knows nothing about tasks: Task and Future live on top of it and talk to it only through call_soon and call_later. As far as the loop is concerned, everything that exists is a callback.

The "What it is made of" tab below shows that diagram whole, with the real field names and arrows for what ends up where. Switch it to "Turn, step by step" and the same picture starts highlighting the parts that do the work at each step.

Six steps of a single turn

The event loop in CPython is the _run_once method in Lib/asyncio/base_events.py. run_forever calls it, and the whole construction is literally this:

# base_events.py:678–687, tag v3.13.7
def run_forever(self):
    ...
    self._run_forever_setup()
    try:
        while True:
            self._run_once()
            if self._stopping:
                break
    finally:
        self._run_forever_cleanup()

Inside _run_once are six steps, and the rest of this article refers to them by number:

1. Sweep cancelled timers (lines 1978–1999).
2. How long we may sleep (2001–2010) — the timeout for the next step.
3. selector.select(timeout) (2012) — the only place the process actually blocks.
4. Process ready I/O (2013) — ready descriptors become callbacks and go into _ready; nothing runs yet.
5. Pop expired timers (2017–2025) — also into _ready.
6. The only place callbacks are called (2027–2051).

Go back to the visualisation above and switch it to "Turn, step by step": it will highlight which part works at each step. In "Recorded run" the same steps are shown against a real program.

The step worth stopping at is the last one. In the sources it carries a comment that explains the scheduler better than any retelling could:

And right after it, the part that makes the scheduler fair:

# base_events.py:2033–2035
ntodo = len(self._ready)
for i in range(ntodo):
    handle = self._ready.popleft()

ntodo is computed before the loop. A callback added to _ready during this pass will not make it in — it waits for the next turn. Without that line, a task that endlessly schedules its own continuation through call_soon would own the loop forever.

How many turns your program makes

This is where the measurements start. Turns can be counted exactly: replace BaseEventLoop._run_once with a counting wrapper before the loop is created. This is not an estimate — these are precisely the iterations that happened.

Three rows in this table deserve a second reading.

An empty program makes six turns, not one. The reason is not the loop but asyncio.run: it is three consecutive run_until_complete calls, and only the first runs your code. The second closes async generators (shutdown_asyncgens), the third the default thread pool (shutdown_default_executor). Each contributes a couple of turns. In "Recorded run" above, those four turns are visible by name at the end.

Three nested awaits cost the same as an empty program. That is, nothing. await on its own never touches the loop — more on that below.

A thousand coroutines produce as many turns as ten. This is probably the single thing to carry away from the article: the number of turns is set by the depth of suspension, not by the number of tasks. Every task that is ready to continue is consumed by one pass over _ready.

What await actually is

A coroutine is a generator with a different protocol. You drive it by calling .send(None), and return comes out as StopIteration.value. This can be checked by hand, with no event loop at all:

async def inner():
    return "the value from return"
 
coro = inner()
try:
    coro.send(None)          # first step — and immediately the last
except StopIteration as e:
    print(e.value)           # the value from return

Now the same thing, but with a suspension. The whole protocol fits in the five lines of Future.__await__:

# futures.py:283–289, tag v3.13.7
def __await__(self):
    if not self.done():
        self._asyncio_future_blocking = True
        yield self  # This tells Task to wait for completion.
    if not self.done():
        raise RuntimeError("await wasn't used with future")
    return self.result()  # May raise too.

yield self is passed up through the entire await chain and emerges as the result of coro.send(None). The _asyncio_future_blocking flag is the agreed signal for "I am a real awaitable, park the task"; the task checks it in tasks.py:324–325.

From which follows the thing that explains the "three nested awaits" row of the table: if no suspending Future is met along the way, the whole await chain collapses without a single trip into the loop. It costs exactly what it costs to create the coroutine objects.

In nanoseconds:

Read this by rows, not by columns: the ratios in the last column were measured within a single run of 3.13.7 and so hold, whereas the two columns are two different builds.

The second and third rows are close, and that is the answer to "is await expensive". Of the 90.8 ns, 69.0 is creating the coroutine object itself — three quarters of it. The await machinery proper costs around twenty nanoseconds. What is expensive is a real suspension with a return into the loop: 2.0 µs, twenty-odd times more.

How a future wakes a task

This is where people go wrong most often, and the mistake sounds innocent: "set_result resumes the coroutine". It does not.

# futures.py:158–170, tag v3.13.7
def __schedule_callbacks(self):
    callbacks = self._callbacks[:]
    if not callbacks:
        return
    self._callbacks[:] = []
    for callback, ctx in callbacks:
        self._loop.call_soon(callback, self, context=ctx)

set_result, set_exception and cancel all end in this function, and it queues a callback. The coroutine continues not here, but in step six of the next turn.

The full loop looks like this:

1. await fut → Future.__await__ does yield self;
2. the task sees the flag, attaches add_done_callback(self.__wakeup) and remembers the future in _fut_waiter (tasks.py:341–343) — from this moment the loop knows nothing about the task;
3. some time later somebody calls fut.set_result(v);
4. __schedule_callbacks puts Task.__wakeup into _ready via call_soon;
5. step six of a turn calls __wakeup, which calls __step, which calls coro.send(None);
6. __await__ returns self.result(), and the function continues on the next line.

asyncio.sleep(delay) is the shortest complete example of that loop:

# tasks.py:713–720, tag v3.13.7
future = loop.create_future()
h = loop.call_later(delay, futures._set_result_unless_cancelled, future, result)
try:
    return await future
finally:
    h.cancel()

A future, a timer, an await — that is all. There is no "sleep magic" in asyncio: there is a timer that after delay seconds puts a result into a future, and that wakes the task through the loop above.

Why one blocking call stops everything

The mechanism is assembled now, so the main consequence can be shown rather than asserted.

Take N tasks, each busy for 100 ms. In one variant that is time.sleep(0.1), in the other await asyncio.sleep(0.1). What is measured is total time, the number of turns, and the duration of the longest turn.

The thing to look at is not the time but the number of turns. In the blocking variant it does not grow at all: one task and fifty tasks both give two turns. What grows is the duration of a single turn — up to 5011 ms.

This is exactly what ntodo = len(self._ready) predicts. All fifty tasks were ready at once, landed in the queue, and were consumed by one pass of step six. The stretches they spent blocked added up.

Note the cooperative variant too: it also has a turn 100 ms long. The difference is not the duration but what happens inside it: in the first case the thread is working and can react to nothing; in the second it sleeps in select() and will wake on any event. On a time axis those two rectangles look identical, which is why they are coloured differently.

The "Responsiveness" tab translates this into something you can feel: a background task asks to be woken every 10 ms while a worker does ten 100 ms chunks of work, yielding between chunks. Both variants yield; the only difference is whether the worker blocks inside a chunk. With a blocking worker the pulse ticked 4 times in a second, with a median interval of 300.9 ms. With a cooperative one — 99 times, median 10.2 ms.

Why 300 and not 100 is a question worth answering, because the answer follows entirely from step six. The pulse loses a turn twice over: a timer that expired during the block is only collected at step 5 of the next turn, and a callback that landed in _ready during a turn only runs a turn later — because of ntodo. So between two ticks of the pulse there is not one turn of the worker but three: its own and the two it lost. Three turns of 100 ms make 300. Confirmed by tracing: the recording shows TaskStepMethWrapper in three consecutive turns before the pulse's Task.task_wakeup appears.

How to see this in a log rather than a profiler

asyncio has a built-in way to catch blocking: debug mode. It is off by default, and the threshold beyond which a callback counts as slow is 100 milliseconds (Lib/asyncio/base_events.py:437).

The mode and the threshold are two independent knobs, and that is what trips people up most. Verified on a 0.25 s block (bench/cancellation/06_debug_slow_callback.py):

The line has one format, but the object inside it changes — and that object tells you what blocked the loop:

• <Handle …> — an ordinary callback scheduled through call_soon;
• <TimerHandle when=… …> — a delayed one, through call_later;
• <Task … coro=<…>> — a coroutine step, which is exactly the case taken apart above: a task that did not yield control.

It is switched on from outside, without touching the code: PYTHONASYNCIODEBUG=1, or python -X dev, or asyncio.run(main(), debug=True). The threshold is set separately and only matters together with the mode: loop.slow_callback_duration = 0.05.

Debug mode also turns on coroutine origin tracking: the "coroutine … was never awaited" warning gains a Coroutine created at <file:line> line, and a forgotten coroutine stops being a mystery.

What changed in 3.12, 3.13 and 3.14

The core of the loop did not change. The body of _run_once is byte-identical between tags v3.13.7 and v3.14.0, all 83 lines; only the first line number moved, 1970 → 1966. The turn counts in the table above are the same across all three versions — the scheduler counts identically. Speed is not compared across versions by these measurements: the three builds differ by more than the language version.

What changed is everything around it.

3.12 — eager tasks. asyncio.eager_task_factory makes a coroutine start executing synchronously inside the task constructor. The documentation is exact here: "Tasks are only scheduled on the event loop if they block". Hence a property worth knowing before switching it on: the speed-up goes only to tasks that finish without suspending once. If the body suspends, there is no gain — the task gets registered with the loop anyway.

3.13 — correctness of cancellation. A case where two nested TaskGroups with simultaneous exceptions could hang was fixed; groups also began keeping a cancellation count (Task.cancelling()). asyncio.Queue.shutdown and Server.close_clients() appeared.

3.14 — introspection and free threading. python -m asyncio ps PID and pstree PID arrived — a view of the task tree of a live process — along with the asyncio.graph module and print_call_graph(). The optimisation claimed in the release notes is "improved by 10-20%", from a new per-thread doubly linked list of tasks. Free-threading builds got "first class support for free-threading builds… scaling linearly with the number of threads". And the change most likely to break existing code: asyncio.get_event_loop now raises RuntimeError when there is no loop instead of silently creating one.

What to do about it

Do not call blocking code in a coroutine. This is the one rule the others follow from, and now it is clear why: there is one thread, and step six is an ordinary for with no preemption.

If blocking is unavoidable — await loop.run_in_executor(...) or asyncio.to_thread(...). The work moves to a thread and the loop goes back into select().

Yielding between chunks of work is not enough. In the measurement above the worker honestly did await asyncio.sleep(0) after every 100 ms chunk — and the pulse still lost 95 of its 99 ticks. One yield per 100 ms of work does not save you.

asyncio.run in a loop is an anti-pattern. Measured: one asyncio.run(noop()) costs 71 µs, while the same coroutine inside an already-running loop costs 0.12 µs. That is 99.8% of the budget spent creating and closing a loop, plus those four shutdown turns. For repeated runs there is asyncio.Runner: it reuses one loop and comes to 10 µs per run — seven times cheaper.

Do not optimise await. It costs 91 ns, and three quarters of that budget goes on creating the coroutine object. What is worth optimising is the number of suspensions, not the number of awaits.

What measured this

The numbers in this article come from these scripts. Each one opens from here, together with the record of the run: what it was measured on, what came out, and with what spread.

• bench/cancellation/06_debug_slow_callback.py
• bench/event-loop/cost.py
• bench/event-loop/runner.py