Commentary: mini-asyncio

A ready queue, a timer heap, and generators driven by send(). One neighbour burning 200ms between yields turns a sleep(1000) into a 1400ms tick — while the loop's own timer heap reports every delivery perfectly on time. A study guide for mini_asyncio.py.

cd mini-asyncio
python3 demo.py                # the aha (§6)
python3 test_mini_asyncio.py   # pins every number this page quotes

1. Orientation

An event loop runs many tasks on one thread by never running two at once. It keeps a ready queue of callbacks that can run now and a timer heap of callbacks that should run later, and it goes round and round: expire the timers that are due, run what is ready, repeat. Tasks are generators, so "suspending" is just returning from send() and "resuming" is calling send() again.

That much is the diagram everyone has seen, and a toy that stopped there would be teaching you that two sleeping tasks can interleave without threads — which is what you already expect an event loop to do.

The thing worth building it for is what the diagram leaves out. There is no preemption. A task runs until it chooses to yield. So a timer is not a promise that your code runs at time T; it is a promise that your code will not run before T. The gap between those two statements is filled by whatever else happened to be in the queue, and this toy measures it.

The measurement has a sting in it. Run demo.py and a task asking for a 1000ms tick, next to one neighbour that burns 200ms of CPU between yields, gets ticked every 1400ms — 40% late, forever, in a steady state that never recovers. Nothing raises. Nothing warns. And the loop's own view of its timer heap says every single timer expired at the exact millisecond it was due, because it did.

By the end you should be able to:

• trace a delivery through its three stages — asked for, expired, callback ran, task resumed — and say which queue each gap came from;
• derive the observed period of a timer from the schedule around it, using (⌈P/R⌉ + hops)·R, and check it against a run;
• say why await asyncio.sleep(1.0) is delivered strictly later than loop.call_later(1.0, cb) asking for the same instant, and by exactly how much;
• point at the one line in the loop that separates "40% late" from "never runs again", and predict what removing it does;
• decide, for an async service you actually operate, whether this effect can bite it — by asking one question about the work between its awaits.

2. The problem this mechanism exists to solve

You have ten thousand network connections and one machine. The obvious answer, a thread per connection, spends most of its memory on stacks and most of its CPU on context switches to discover that nothing has arrived. The event loop's bet is that if the work is dominated by waiting, you can multiplex all of it onto one thread and keep a few hundred bytes of state per connection instead of a megabyte of stack.

That bet pays enormously, and it is paid for with a specific currency: the scheduler loses the ability to interrupt you.

A kernel thread scheduler is preemptive. It owns a timer interrupt, and when your thread's slice expires the hardware takes the CPU away whether your code consents or not. That is what makes a thread's sleep(1.0) accurate to within the scheduler's granularity no matter what its neighbours are doing: the neighbour cannot refuse to be interrupted.

An event loop has no timer interrupt. It regains control only when a task returns. So the same sleep(1.0), expressed cooperatively, means "put me on the heap, and hand me back the CPU on some pass of the loop at or after T" — and which pass that is depends entirely on the other tasks.

The competing goals that make more than one design defensible:

• Throughput vs. latency. Running a big batch of ready callbacks in one pass amortises the loop's own overhead; checking the clock between every callback keeps timers tight and wastes time doing it.
• Fairness vs. simplicity. You could give due timers priority over already-queued work, or run tasks by deadline, or give each task a budget. Every one of those costs a data structure and a policy, and every one of them is still powerless against a task that simply does not yield.
• Honest timers vs. cheap timers. A loop could measure how late each delivery was and complain. Almost none do by default, because the measurement costs a clock read per callback on the hottest path in the process.

And the loop must resolve all of this without the one instrument that would settle it — it cannot ask a task how long it intends to run, and it cannot stop it once it starts.

3. Background you need

The two flagged as ☋ carry the result. Cooperative scheduling is why the effect exists; the ready queue and the future hop are where the milliseconds actually go, and they are separable — §6.3 shows one of them is worth 200ms on its own.

4. The mental model

One pass of the loop. Time only ever moves inside the shaded box.

The mental shortcut to carry away: R is one full pass of the ready queue — the sum of the CPU every runnable task burns before the loop gets back to the top. A timer cannot be delivered at a finer granularity than R, and it costs one extra R for each queue hop between the timer and your code. Everything in §6 is that sentence with numbers in it.

5. Reading the source

5.1 The clock, and the two things that move it

    def run(self, until):
        """Run until the virtual clock reaches `until`, or nothing is left."""
        while self.clock < until:
            if not self.ready:
                if not self.timers:
                    return
                # Nothing runnable: idle forward to the next deadline. This is
                # the only place the clock moves without a task having burned
                # CPU, and it is why a lone sleeper is never late.
                self.clock = max(self.clock, self.timers[0][0])
            self.run_once()

This is the determinism decision, and it is worth more than it looks. A real loop calls select(timeout) here and lets the OS burn the wall-clock interval. This one jumps the clock to the next deadline instead — but only when there is genuinely nothing runnable.

That asymmetry is the entire model. Idle time is free and exact, so a task with no neighbours lands on its deadline to the millisecond. Busy time is paid for by whoever burned it, so a task with neighbours lands wherever their arithmetic puts it. Nothing else in the file reads a clock at all.

The clock is an integer count of milliseconds, which is not fussiness; §7.3 shows the float version producing periods like 1.4000000000000004, 1.4000000000000008, 1.4000000000000012 — drifting, unquotable, and impossible to derive by hand.

5.2 run_once — the whole scheduler, in nine lines

    def run_once(self):
        """One pass, in CPython's order: expire timers, then run a snapshot
        of the ready queue.
        """
        while self.timers and self.timers[0][0] <= self.clock:
            _, _, timer = heapq.heappop(self.timers)
            timer.expired_at = self.clock       # noticed exactly on time
            self.ready.append(timer.callback)   # ...and queued behind the rest

        # A SNAPSHOT, not a drain. Anything these callbacks schedule waits for
        # the next pass. Change `for _ in range(len(self.ready))` to
        # `while self.ready:` and a task that reschedules itself every step
        # never lets the loop reach a timer again -- silently, forever.
        for _ in range(len(self.ready)):
            self.ready.popleft()()

Two decisions, both load-bearing, and both easy to read past.

self.ready.append(timer.callback). A timer that comes due does not get priority. It goes to the back of a queue that already contains whatever was scheduled on the previous pass. This is why expired_at is always exactly the deadline while fired_at is not: the heap did its job the instant the clock reached the deadline, and then the callback stood in line. §7.2 runs the variant that jumps the queue, and it recovers half the lateness — not all of it.

for _ in range(len(self.ready)). The pass is bounded to the callbacks that were already there. A callback that calls call_soon — which every burn does, and which every await in real asyncio does — is queued for the next pass and cannot extend this one. That single expression is what guarantees the loop reaches the top of run_once again, which is the only place timers are ever examined. §7.1 removes it, and the heartbeat stops forever without an error.

5.3 Task.step — resumption is one trip through the queue

    def step(self):
        """Resume the generator once and dispose of whatever it yields.

        Entering `step` *is* the delivery: `self.loop.clock` right now is when
        this task's own code got the CPU, which is the only reading its author
        would ever be able to observe.
        """
        if self.deadline is not None:
            self.loop.trace.append(Wake(self.name, self.deadline,
                                        self.expired_at, self.fired_at,
                                        self.loop.clock))
            self.deadline = self.expired_at = self.fired_at = None

        try:
            kind, arg = self.coro.send(None)
        except StopIteration:
            return

        if kind == BURN:
            self.loop.clock += arg
            self.loop.call_soon(self.step)
        elif kind == SLEEP:
            self._suspend(arg)
        else:
            raise ValueError(f"unknown command {kind!r}")

self.loop.clock at the top of step is the only timestamp a task's author could ever observe — it is what time.monotonic() would return on the first line after their await. Recording it here, rather than when the timer expired, is what lets §6 put the loop's opinion and the task's experience in adjacent columns and show they disagree.

The BURN branch is the model of ordinary Python between two awaits: it costs time, and then it goes to the back of the queue. Note what it is not — it is not a special "CPU-bound task" mode. burn(200) is exactly do_200ms_of_work(); await asyncio.sleep(0), which is the shape of a task that its author believes is well-behaved, because it does yield, on every single iteration.

5.4 _suspend — where the second hop comes from

    def _suspend(self, delay):
        """Model of `asyncio.sleep(delay)` for delay > 0.

        CPython does not arm a timer that resumes the task. It arms a timer
        whose callback resolves a *future*, and awaits that future:

            h = loop.call_later(delay, futures._set_result_unless_cancelled,
                                future, result)
            return await future

        (verbatim shape of `inspect.getsource(asyncio.sleep)`). So the wakeup
        costs two trips through the ready queue, not one.

        `loop.hops == 1` is the counterfactual: the armed callback resumes the
        task itself, which is what `loop.call_later(delay, cb)` gives you.
        """
        loop = self.loop
        self.deadline = loop.clock + delay
        fut = Future(loop)
        fut.waiter = self.step

        def fire():                   # hop 1: the callback the timer armed
            self.expired_at = timer.expired_at
            self.fired_at = loop.clock
            if loop.hops == 2:
                fut.set_result()      # -> call_soon(self.step), a second trip
            else:
                self.step()           # resumed in place, no second trip

        timer = loop.call_later(delay, fire)

This is the toy's one deliberate act of archaeology. The docstring makes a claim about CPython; here is the claim being checked rather than trusted. inspect.getsource(asyncio.sleep) on the declared interpreter contains, in order:

CPython does not arm a timer that resumes your task. It arms a timer whose callback resolves a future, and awaits that future. So the wakeup path is timer expires → callback runs → future resolved → task scheduled → task runs, and there are two queue boundaries in it, not one.

hops == 1 is the counterfactual, and it is a fair one: it is precisely what loop.call_later(delay, cb) gives you, where the callback you registered is the work. Everything else about the run is held constant. §6.3 measures the difference in the toy and then against real CPython.

5.5 Future.set_result — the line the hop is made of

    def set_result(self):
        self.done = True
        if self.waiter is not None:
            waiter, self.waiter = self.waiter, None
            self.loop.call_soon(waiter)          # hop 2

call_soon(waiter), not waiter(). Resolving a future never runs the waiter; it schedules it.

That is not an oversight in asyncio, and it should not be "fixed". Calling the waiter directly would mean set_result can execute arbitrary user code re-entrantly, in the middle of whatever was calling it — a callback could resolve a future, and find that by the time set_result returned, the world had changed underneath it. Deferring through the queue makes every resumption happen at a known place with an empty stack above it. The price is one pass of the loop, and this toy exists to show you what that pass costs when the loop is busy.

6. The demo, and what it proves

The schedule is two tasks. One asks for a 1000ms period and does nothing else. The other burns 200ms of CPU and yields, forever.

def heartbeat(period):
    """A well-behaved task: asks for a fixed period and does no work."""
    while True:
        yield sleep(period)


def hog(chunk):
    """A neighbour that burns `chunk` ms of CPU between yield points.

    It is not badly written: it *does* yield, every single iteration. It
    simply does a chunk of ordinary Python before it does.
    """
    while True:
        yield burn(chunk)

Neither is badly written. The hog yields on every iteration; a reviewer looking for a missing await would find nothing.

6.1 The transcript

python3 demo.py

6.2 The timer is punctual; the task is late

Look only at the expired column: 1000, 2400, 3800, 5200, 6600, and the lateness beside each is 0. Every timer in this run was noticed on the exact millisecond it came due. The heap is not the problem, the clock is not the problem, and nothing is being dropped — all five deliveries arrive, none is skipped or coalesced.

This is the part worth carrying around. If you instrumented this loop the obvious way — record when, compare against the clock when you pop the heap — your dashboard would show a flat zero and you would go looking elsewhere. The lateness lives in the two queue hops after the heap has already done its job correctly, and the only place it is observable is inside the sleeping task, on the first line after its await.

The failure is silent in a stronger sense than "no exception is raised": the component best placed to notice it is measuring the one interval that is genuinely fine.

Now the arithmetic behind 1400.

The hog burns 200ms and yields, so a full pass of the ready queue costs R = 200ms. That makes the loop's timer checks land on a 200ms grid: it looks at the heap at 200, 400, 600, … and nowhere in between, because between those points it is inside the hog and has no way to take the CPU back.

• The heartbeat asks at t=0 for t=1000. 1000 is on the grid, so the sweep at 1000 expires the timer: expired = 1000, late by 0.
• The timer's callback goes to the back of the ready queue, behind the hog's step which was queued on the previous pass. That pass runs [hog.step, fire]: the hog burns 200 → clock 1200, then fire runs: callback = 1200, late by 200. That is one R.
• fire resolves the future, which call_soons the heartbeat — for the next pass, because this one was snapshotted. That pass runs [hog.step, beat.step]: the hog burns 200 → clock 1400, then the heartbeat resumes: ran = 1400, late by 400. That is a second R.

0 + R + R = 400ms late, and because the heartbeat re-arms from 1400 (not from 1000), the drift does not accumulate — it locks into a steady state where every subsequent request is also 400 late: 2400 → 2800, 3800 → 4200. Hence a period of 1000 + 400 = 1400, forever.

6.3 The hop nobody predicts: 1200 vs 1400

Section 3 of the demo holds everything constant and changes only how the timer reaches the sleeper. loop.call_later style: 1200. asyncio.sleep style: 1400. One extra R, on every beat, bought by an indirection that appears nowhere in the calling code.

This is a claim about real CPython, so it was measured against real CPython. A scratch script reads inspect.getsource(asyncio.sleep), then runs the same two shapes with a real time.monotonic() burn loop. These are the only wall-clock numbers on this page, and they are valid only for this banner:

Four configurations, four matches: 1.201 ≈ 1200, 1.403 ≈ 1400, 1.500 ≈ 1500, 1.800 ≈ 1800.

The hog burns at each tick column is the cleanest evidence on this page, because it is an integer and no timing noise can smear it. At chunk=200, call_later is delivered after the hog's 6th burn and asyncio.sleep after its 7th — one whole burn apart, every tick, exactly as the model says. 6 × 200 = 1200 and 7 × 200 = 1400. At chunk=300 it is the 5th against the 6th: 1500 and 1800.

6.4 The closed form

Demo section 4 checks the general rule against runs:

The two terms are the two separate things that go wrong, and it is worth keeping them apart:

• ⌈P/R⌉ · R — rounding up to the grid. Your deadline gets served at a granularity of R, so if R does not divide P you lose the remainder before anything else happens. This is why chunk=300 costs more than chunk=400 at three hogs would suggest: ⌈1000/300⌉ = 4, so the deadline at 1000 is not even looked at until 1200.
• + hops · R — the queue hops. One R for standing behind the already-queued work, one more for the future's call_soon.

Note the third block: with three hogs at 400ms, R = 1200 already exceeds the 1000ms period, ⌈P/R⌉ = 1, and the beat is delivered every 3600ms — a 3.6× inflation of a timer nobody touched. test_closed_form_predicts_every_combination checks this over 180 combinations (5 periods × 6 chunks × 2 hop counts × 3 hog counts) and every one matches.

6.5 The only lever is R

The instinct on reading the above is to reach for await asyncio.sleep(0). That instinct is confused, and the confusion is worth naming: sleep(0) is what makes a chunk of work a yield point at all. The hog already has one — burn(200) is work(); await sleep(0). Adding another one does not help, because lateness is bounded below by hops · R, and R is set by how much work you do between yields, not by how many yield statements you write.

Demo section 5, and a scratch counterfactual in more detail:

The hog does the same 200ms of work in every row. What changes is how finely it is chopped, and the lateness is 2 × chunk down the whole column — the hops · R term, with the grid term vanishing once chunk divides 1000.

The uncomfortable consequence: the chunk you are allowed to hold is set by the tightest deadline anywhere else in the process, which is a number your module cannot see. A library that does 50ms of parsing between awaits is perfectly well-behaved next to a 10-second health check and is a 100ms latency bug next to a 20ms one, and nothing about the library changed.

6.6 The boundary condition — where this vanishes

The effect disappears when R ≪ P. As R → 0, ⌈P/R⌉·R → P and hops·R → 0, so the observed period converges on exactly what was asked for. That is not a hypothetical: it is the chunk=1 row above, 1002 against a request of 1000, and it is the regime real async servers are designed for.

Concretely, this never bites the thing async is famous for. A proxy holding 10,000 connections, doing tens of microseconds of header parsing between awaits, has R in the low milliseconds even with hundreds of tasks runnable at once — its timers are accurate to well under 1% and the analysis in this page is a rounding error. Cooperative scheduling is exactly the right answer there, and the absence of preemption costs nothing, because no task ever wanted the CPU for long enough for preemption to matter.

It bites when one task's between-await work is a meaningful fraction of the tightest timer in the process. In practice that means: a JSON or protobuf decode of a multi-megabyte payload, template rendering, a compression or hashing pass, re against a big string, a synchronous DB driver call someone forgot to move to a thread, an ORM materialising ten thousand rows. None of those look like "blocking the event loop" in review, because they all return promptly on the data the author tested with.

And the reliable early symptom is not a slow endpoint — it is a heartbeat. Health checks, gossip timers, lease renewals and metrics flushes are the tasks with the tightest periods and the least work, so they are the first things to go late, and going late is the one thing they are not designed to report.

6.7 The trace is pinned by tests

python3 test_mini_asyncio.py

7. Design decisions and roads not taken

7.1 The load-bearing line: for _ in range(len(self.ready))

run_once runs a bounded snapshot of the ready queue. Change that one expression to while self.ready: — a change most reviewers would call a simplification, and which passes any test that does not involve a timer — and here is the whole result:

42 deliveries become 0. Not late — never. The drained loop ran for 10,000 virtual seconds (that is the scratch script's escape hatch, not a natural stopping point) and the heartbeat's timer sat in the heap the whole time, expired and unexamined. Removing the escape hatch and asking the loop to stop at until=3000 confirms the obvious: a single run_once call never returns at all, so until is never re-checked.

The mechanism is worth stating precisely, because it is the sharpest possible statement of what "cooperative" means. Timers are examined at exactly one place: the top of run_once. The hog's burn ends with call_soon(self.step), which re-arms it inside the current pass. With the snapshot, that new callback is out of scope for this pass, the pass ends, and control returns to the top where timers are checked. Without it, the queue is never empty, the while never exits, and the top of run_once is never reached again — for the life of the process.

So the difference between a 40%-late heartbeat and a heartbeat that never fires again is not the hog, not the timer, and not the workload. It is whether the loop bounds one pass.

This is not a distinction CPython gets right by luck. Reading _run_once out of the installed stdlib on the declared interpreter:

ntodo = len(self._ready) is this toy's snapshot line in production, and the comment above it is a deliberate statement of the invariant — including the parenthetical that matters most, "after another I/O poll", which is the real loop's way of saying that control returns to the top, where timers are checked.

7.2 Giving due timers priority: buys back half

If the lateness comes from timers queueing behind existing work, the obvious fix is to stop making them queue. A counterfactual that puts expired timers at the front of the ready queue instead of the back:

It works, and it works exactly halfway: 1400 → 1200. The callback now runs at 1000, dead on. But it then resolves a future, whose call_soon puts the task on the next pass, and that pass still starts with the hog. The second R is untouched.

That is the useful lesson from the road not taken. You cannot fix this with a priority policy, because the cost is not one queue decision — it is one per hop, and the hops are structural. This is also why the road stays not taken: it doubles the policy surface of the scheduler to halve a number that a 100ms-smaller chunk would remove entirely.

7.3 Integer milliseconds, not float seconds

The clock was floats first. The repo's rule is that every transcript must be byte-identical on every machine, and floats technically satisfy it — IEEE 754 is deterministic. They fail a different requirement: the reader has to be able to derive the numbers.

A hog burning 0.2 per pass arrives at what should be the 2.2 deadline holding 2.1999999999999997, and timers[0][0] <= self.clock is then decided by the last bit of a mantissa. The whole schedule shifts by one pass on the strength of it. Running the identical schedule both ways:

The float row is not wrong, exactly — it is unquotable. §6.2's derivation ("0 + R + R = 400") cannot be written against numbers that drift in the fifteenth place, and a reader checking the page by hand would conclude the arithmetic was broken. Integers cost one unit of awkwardness in the API (everything is milliseconds) and buy a page whose every number can be reproduced with a pencil.

7.4 Generators, not async/await

The toy drives generators with send() rather than real coroutine objects. Real async def coroutines would also work — they expose send() too, which is exactly how asyncio drives them — but they cannot yield a value to their driver without an awaitable protocol, so the toy would need an __await__ shim on every command purely to look modern. Generators make the suspension points visible in the source, which is what a reader is here for.

7.5 Roads not taken elsewhere

• A sleep(0) command. There isn't one, because it would be a synonym for burn(0) and would suggest a distinction the loop does not make. §6.5's point is precisely that sleep(0) is not a lever.
• Per-task time budgets. A loop could track how long each callback ran and complain past a threshold — asyncio does this in debug mode. Useful diagnostics, but it changes nothing about the schedule, and the toy is about the schedule.
• Deadline-ordered dispatch (EDF). Running ready tasks in deadline order is a real design used by real schedulers. It is absent because it cannot help here: the hog has no deadline and is already running when the heartbeat's arrives. No dispatch order rescues you from a task that will not yield.

8. What's simplified vs. the real thing

8.1 The model is a lower bound on real lateness, never an over-estimate

This is the disclosure that matters most, because the toy's whole credibility rests on it. Tasks declare their own CPU cost. burn(200) means "assume this took 200ms", and the loop simply adds 200 to an integer. That is a fiction in three specific directions, and every one of them makes the real world worse than the model, never better:

• No OS scheduler jitter. The real process shares the machine. Its thread gets descheduled mid-callback and the wall clock keeps running.
• No GC pauses. A collection during the hog's burn extends the pass.
• No selector latency. A real loop calls epoll/kqueue between passes, which has its own cost and its own resolution; the toy jumps the clock for free.
• The cost itself is a guess. Real between-await work is data-dependent — the JSON blob is 4KB in your test and 40MB in production — so the real R is a distribution, not the constant this toy uses.

So the model gives you the floor. The measurement in §6.3 is the evidence: the model says exactly 1400 and real CPython delivered 1.403, 1.401, 1.401 — always at or above, never below. Read every number on this page as "at least this late".

The virtual clock is also why the toy is honest about something a wall-clock version could not be. A real-time version of §6.4's 180-combination table would take hours to run and would produce a different table every time, which is another way of saying the closed form could not have been found.

8.2 The other simplifications

• No I/O at all. There is no selector, no sockets, no file descriptors — the single largest omission. A real _run_once computes a select() timeout from the nearest timer, and that computation is a whole second source of lateness the toy does not model: if the loop is blocked in select with a 5-second timeout and a call_soon arrives from another thread, it needs the self-pipe trick to wake up at all.
• No cancellation. Real tasks can be cancelled, which is why asyncio.sleep keeps a handle h and calls h.cancel() in a finally — visible in the source quoted in §5.4, and absent here. Cancellation is what makes futures genuinely necessary rather than an indirection, and skipping it lets the toy present the future as pure cost, which is unfair to it.
• No exception propagation. A StopIteration ends a task silently and anything else escapes into run_once. Real asyncio routes exceptions into the task's future, and a future nobody awaits produces the "Task exception was never retrieved" warning that exists because of exactly this.
• One waiter per future. Future.waiter is a single slot; asyncio keeps a callback list, because many tasks can await one future.
• No gather, no nurseries, no composition. Tasks are independent. Structured concurrency changes who waits for whom, not how a pass is scheduled.
• A single loop on a single thread. No run_in_executor, which is the actual production answer to the hog: move the CPU-bound work to a thread pool, where a preemptive scheduler exists and this entire page stops applying.
• No slow-callback warning. Real asyncio in debug mode logs Executing %s took %.3f seconds (base_events.py, inside _run_once) when a callback exceeds loop.slow_callback_duration, which defaults to 0.1 — 100ms, checked on the declared interpreter. That is the closest thing production has to an alarm for this, and it has three problems. It is off unless debug mode is on. It reports the hog, not the victim — it would never mention the heartbeat that went 40% late. And its threshold is not even monotonic in the harm: a 90ms chunk never trips the 100ms warning and inflates the heartbeat to 1260ms (260 late), while a 100ms chunk does trip it and inflates it only to 1200ms (200 late). The quieter hog is the more damaging one, because 90 does not divide 1000 and the grid term collects the difference.

9. Check yourself

Answer before expanding. Each answer is derivable from the source.

10. Further reading

• PEP 3156 — Asynchronous IO Support Rebooted — Guido van Rossum's design document for asyncio. Its call_soon definition and its guarantee that "callbacks are called in the order in which they were scheduled" are the specification of call_soon/call_later this toy models, and it is candid about cooperative scheduling's terms.
• Lib/asyncio/base_events.py — the real thing. Read _run_once; ntodo = len(self._ready) is §7.1's load-bearing line in production, with the comment explaining why.
• Lib/asyncio/tasks.py — sleep is eleven lines. The call_later + await future pair is the second hop measured in §6.3.
• asyncio developer guide — Debug Mode — the slow-callback warning, the closest thing production has to an alarm for this. Note that it is off by default and reports the hog, not the victim.
• asyncio event loop reference — call_soon, call_later, and run_in_executor, which is the standard answer to the hog and the one that leaves cooperative scheduling entirely.
• PEP 342 — Coroutines via Enhanced Generators — where send() comes from, and therefore why a generator can be a task at all.
• A Web Crawler With asyncio Coroutines — Guido van Rossum and A. Jesse Jiryu Davis, in 500 Lines or Less. Builds an event loop and a coroutine runtime from scratch, then a real crawler on top. The natural next toy after this one: it adds the selector and the I/O this page leaves out.
• heapq — the timer heap. The (when, seq, item) tuple trick, which keeps equal deadlines FIFO and avoids comparing the payloads, is standard and worth stealing.