Commentary: stackless-vs-stackful

Two green-thread runtimes over one program. A library function gains one line and starts suspending: the stackful column silently returns 150 where 200 is the only correct answer, the stackless one refuses to run — and colouring all four frames above it to make it run again also returns 150. A study guide for runtimes.py.

cd stackless-vs-stackful
python3 demo.py            # the aha (§6). Panel 7 takes ~20s; the rest is instant
python3 test_runtimes.py   # pins every number this page quotes

1. Orientation

A green thread is a task the language schedules instead of the operating system. There are two ways to build one, and they differ in exactly one thing: where a task is allowed to suspend.

• Stackless. A task is a generator (or a coroutine). Suspending is a keyword — yield, await — and a keyword only works in a frame that the compiler already turned into a generator. If a function five levels down wants to suspend, every frame between it and the scheduler has to become a generator too. That is function colouring. Python's async/await is this. So is JavaScript's.
• Stackful. A task owns a real stack. Suspending is a function call, so it works at any depth, in any kind of frame, and no caller above it is edited or even recompiled. Goroutines are this. So are Java's virtual threads.

The received wisdom about the trade is that colouring is an ugly tax you pay for cheap tasks, and that the stackful version is the same thing without the paperwork. This toy runs one program on both and measures what the tax actually buys.

The measurement has a sting in it. A library function called io_read gains one line — it suspends between reading the row and returning it. No frame above it is edited. The stackful column silently returns 150 where 200 is the only correct answer. The stackless column refuses to compile the thought: TypeError: unsupported operand type(s) for +: 'generator' and 'int'. Then you do what the error tells you and add yield from to all four frames above it — and it runs, and returns 150.

Colouring bought visibility. It did not buy correctness.

And then the part that inverts the folklore. Against real asyncio and real OS threads, 20 trials each on the same workload: the cooperative version was wrong on 20 of 20, the preemptive one on 0 of 20. Cooperative scheduling did not make the race rarer. It made it the only behaviour the program has.

By the end you should be able to:

• say what "function colouring" costs, as an integer, for a given call depth — and say why every tutorial example is written at the one depth where it costs nothing;
• look at a critical section and decide whether a suspension inside it is survivable, without knowing anything about the scheduler;
• explain why "cooperative concurrency has no data races" is true about memory and false about invariants;
• name the three ways an un-awaited coroutine gets past you in Python, and the one place the interpreter says anything at all;
• decide, for a service you operate, whether adding an await to an existing library function is a compatible change.

2. The problem this mechanism exists to solve

Ten thousand connections, one machine. A thread each spends its memory on stacks and its CPU on switching between them to discover nothing arrived, so every runtime that wants a lot of concurrency ends up multiplexing many logical tasks onto few OS threads. That much is settled, and §6.6 measures the prize: 192.5 bytes of state for a suspended green task against 38,789 bytes of resident memory for a parked OS thread, and a hard ceiling of 16,383 OS threads on the machine this ran on against 100,000 green ones that did not raise an eyebrow.

The design question is not whether to multiplex. It is what a task is allowed to do when it wants to give the CPU back, and there are two honest answers with different bills.

• Suspension as a keyword costs you the call stack. The compiler builds a little state machine per function, and one function can only suspend if it is one of those state machines — which its callers must then also be. The tax is paid in source code, once per frame, and it propagates upward forever. Bob Nystrom's "What Color is Your Function?" is the canonical complaint.
• Suspension as a call costs you a stack per task. Something has to be able to park a whole native stack and put it back later, which means either a real OS thread (expensive, and what this toy uses because Python offers nothing else) or a runtime that can allocate, grow and relocate stacks itself (cheap, and what Go and the JVM spent years building).

The competing goals that keep both designs alive:

• Cheap tasks vs. unrestricted suspension. You can have a few hundred bytes per task, or you can suspend from anywhere. Getting both requires moving stacks around at runtime, which requires knowing where every pointer into them lives — which is why it shows up in garbage-collected runtimes with their own calling convention and not in CPython.
• Visibility vs. compatibility. await is a marker at every call site that can suspend. That is genuinely useful information, and it is also precisely what stops you adding suspension to an existing function without breaking every caller. The same property is the feature and the bug.
• Certainty vs. rarity of failure. A cooperative scheduler switches at fixed source locations, so its interleavings are few and reproducible. A preemptive one switches anywhere, so its interleavings are astronomically many and each is rare. §6.4 shows what that does to a lost update: it does not remove it, it changes it from a heisenbug into a constant.

3. Background you need

The three flagged ☋ carry the result. yield from is how colouring is spelled, function colouring is what is being counted, and the lost update is the failure that both runtimes produce identically — which is the only reason the comparison says anything.

4. The mental model

One program. The library owns only the bottom frame.

The shortcut to carry away: a suspension point is a place where every invariant you are half-way through establishing becomes visible to everybody else. Stackless spelling makes that place visible in the source at every level; stackful spelling makes it invisible above the frame that does it. Neither spelling makes the place safe, and §6.3 measures the difference between the two spellings at exactly zero.

5. Reading the source

5.1 Green — the stackless runtime, in twenty lines

class Green:
    """STACKLESS. A task is a generator, driven with send(); a task suspends
    by returning from send() and resumes on the next one. Plain FIFO."""

    def __init__(self):
        self.q = collections.deque()
        self.switches = 0

    def spawn(self, gen):
        self.q.append(gen)

    def run(self):
        while self.q:
            g = self.q.popleft()
            try:
                g.send(None)
            except StopIteration:
                continue
            self.switches += 1
            self.q.append(g)

There is no suspension machinery here at all, and that is the point. The scheduler never causes a suspension; it calls send and the generator comes back when it feels like it. Everything this toy is about happens in the type system above this class, not in it: g must be a generator, so whatever built g must have been a generator function, so whatever suspends inside it must have had a yield reachable through an unbroken chain of yield from.

Note what switches counts — a send that returned rather than raising StopIteration. That is the honest definition of a context switch in a stackless runtime: it is a function return.

5.2 Stackful.suspend — the same idea as a call

    def suspend(self):
        """Hand the baton back and wait to be given it again.

        This is an ordinary method call, so it works at ANY stack depth, in
        any kind of frame. That single fact is the whole toy.
        """
        slot = self.cur.slot
        self.back.release()
        slot["sem"].acquire()

Three lines, and one of them is bookkeeping. The task's OS thread blocks on its own semaphore; the scheduler, blocked on back, wakes up and gives the baton to the next slot. The Python frames of the suspended task stay exactly where they were, on a real stack, because nobody unwound them — which is the entire difference from Green, where suspension is a return and the frames above the yield had to be generators precisely so that they could be unwound and rebuilt.

self.cur is a threading.local(), so suspend needs no argument to work out who is calling it. That is not a convenience: it is what makes the module level suspend() below callable from a frame that has never heard of the scheduler.

5.3 The suspension primitive, reachable from anywhere

def suspend():
    """The stackful suspension primitive, reachable from anywhere -- exactly
    as `runtime.Gosched()` is in Go and a blocking call is on a Loom virtual
    thread. Nothing in the signature of a caller records that it can happen.
    """
    SCHED.suspend()

The last sentence of that docstring is the claim the whole toy tests. sf_deposit calls sf_repo_get, whose type, signature, name and call site are identical before and after the library learned to suspend. There is no declaration anywhere in the program that a switch can occur inside it — and §6.3 shows that this missing declaration is worth exactly 50 lost increments and nothing else, because the coloured version, which does declare it, loses the same 50.

5.4 The application, stackful: five frames, one marker

def sf_io_read(bank, acct):
    if WHERE == "before_read":
        suspend()
    v = bank[acct]                  # the row is read here...
    if WHERE == "after_read":
        suspend()                   # <-- THE ONE LINE THE LIBRARY ADDS
    return v                        # ...and the reply reaches us here

def sf_db_fetch(bank, acct):
    return sf_io_read(bank, acct)

def sf_repo_get(bank, acct):
    return sf_db_fetch(bank, acct)

def sf_deposit(bank, acct, amt):
    b = sf_repo_get(bank, acct)     # critical section starts
    b = b + amt
    bank[acct] = b                  # critical section ends

def sf_teller(bank, acct, n):
    for _ in range(n):
        sf_deposit(bank, acct, 1)

WHERE is a module global set by run_stackful, and it selects between three one-line editions of the library's io_read: no suspension, suspension before the read, suspension after it. Reading a configuration flag inside io_read is not how a real library works — a real one just has the line or does not — but it lets the counterfactual be a parameter instead of a second copy of the file, and §6.3 is the reason it is worth doing.

The four frames underneath are the whole exhibit. sf_db_fetch, sf_repo_get, sf_deposit and sf_teller are byte-identical across all three editions of the library, and test_the_bank_workload_is_depth_four asserts that none of them contains the string yield or suspend. A reviewer looking at a diff of this program when the library changed would see nothing, because there is nothing to see.

sf_deposit is the failure, and it is worth reading as three separate instructions rather than one idea. b = sf_repo_get(...) is a read of shared state. bank[acct] = b is a write derived from it. The invariant "nobody else touched bank[acct] in between" is asserted by nothing at all — it is merely true, as long as no suspension lands on the line between them.

5.5 The application, stackless, after the library changed

def g2_io_read(bank, acct):
    v = bank[acct]
    yield                           # <-- THE ONE LINE THE LIBRARY ADDS
    return v

def g2_db_fetch(bank, acct):
    return g2_io_read(bank, acct)

def g2_repo_get(bank, acct):
    return g2_db_fetch(bank, acct)

def g2_deposit(bank, acct, amt):
    b = g2_repo_get(bank, acct)
    b = b + amt
    bank[acct] = b

def g2_teller(bank, acct, n):
    for _ in range(n):
        g2_deposit(bank, acct, 1)
    yield

This is the same edit — one line, in the library, nothing above it touched — and it does not run. g2_io_read is now a generator function, so calling it returns a generator object without executing a single line of its body. That object travels up through g2_db_fetch and g2_repo_get, both of which are perfectly happy to return something they never look at, and dies in g2_deposit at b = b + amt.

The line that raises is two frames above the line that changed, and it mentions neither generators nor suspension. That distance is why §6.5 matters: the error is loud here only because somebody did arithmetic on the value. §6.5 runs the two callers that don't.

g2_teller ends with a bare yield for a mundane reason: Green.spawn takes a generator, so a task has to be a generator function whether or not it ever suspends. That is the floor of colouring — even the version of this program with no suspension anywhere (g1_teller, lines 160–163) pays it.

5.6 The same program with all four frames coloured

def g3_io_read(bank, acct):
    v = bank[acct]
    yield
    return v

def g3_db_fetch(bank, acct):
    return (yield from g3_io_read(bank, acct))

def g3_repo_get(bank, acct):
    return (yield from g3_db_fetch(bank, acct))

def g3_deposit(bank, acct, amt):
    b = yield from g3_repo_get(bank, acct)
    b = b + amt
    bank[acct] = b

def g3_teller(bank, acct, n):
    for _ in range(n):
        yield from g3_deposit(bank, acct, 1)

Four edits, and every one of them is mechanical: put yield from in front of the call and, where the value is used, unwrap the result. Nothing about the program's logic changed. A code reviewer would approve this diff in seconds, and would be approving a diff that does not fix the bug.

Look at g3_deposit beside sf_deposit. It is now completely explicit: b = yield from g3_repo_get(...) says, in the source, on the line, that this task may lose the CPU here — and then two lines later it writes b back anyway. The information that the stackful column was missing is present, visible, and syntactically unavoidable, and the program produces the same 150. That is the strongest single sentence this toy can offer about colouring: it is a notification mechanism, and the notification is delivered to a reader who has to know what to do with it.

5.7 chain — the depth experiment, generated rather than asserted

def chain(depth, style):
    """Source for a task with `depth` frames above its suspending call.

    style: 'stackful' | 'coloured' | 'uncoloured' (the last two stackless).
    Returns (source, edits), `edits` counting the frames that had to gain a
    suspension marker they did not previously carry.
    """
    mark = "    suspend()" if style == "stackful" else "    yield"
    if depth == 0:                          # the task body suspends directly
        return "\n".join(["def task():", "    v = 7", mark,
                          "    out.append(v + 1)"]), 0
    src = ["def leaf():", "    v = 7", mark, "    return v"]
    call, edits = "leaf()", 0
    for i in range(depth - 1):
        if style == "coloured":
            src += [f"def f{i}():", f"    return (yield from {call})"]
            edits += 1
        else:
            src += [f"def f{i}():", f"    return {call}"]
        call = f"f{i}()"
    if style == "coloured":
        src += ["def task():", f"    v = yield from {call}",
                "    out.append(v + 1)"]
        edits += 1
    else:
        src += ["def task():", f"    out.append({call} + 1)"]
        if style == "uncoloured":
            src += ["    yield"]           # a Green task must be a generator
    return "\n".join(src), edits

"Colouring costs D edits at depth D" is the sort of statement that is obviously true and worth not believing. So the toy writes the program at each depth, in all three styles, execs it and runs it. The edits counter is incremented at the exact places a yield from is emitted, so it counts something that happened rather than something asserted.

The depth == 0 branch is the boundary, and it is deliberately a separate case rather than a loop that happens to run zero times. At D = 0 the suspension is in the task's own body: there is no caller to inform, so the uncoloured and coloured styles produce identical source, and so does the stackful one modulo the spelling of the primitive. §6.7 runs that row, and it is the one place on this page where the two runtimes are the same tool.

out.append({call} + 1) rather than out.append({call}) is load-bearing in a small way. The + 1 is what forces the caller to consume the value, which is what makes an un-coloured caller fail loudly. Drop it and the uncoloured column passes silently at every depth — which is not a bug in the experiment, it is §6.5.

6. The demo, and what it proves

python3 demo.py

Seven panels; panel 7 spawns OS threads until macOS refuses, which takes about twenty seconds. Everything else is instant.

6.1 The headline

The switches column is worth deriving, because it shows the two runtimes doing the same amount of scheduling.

• ACT 1, both columns: 2. Nothing suspends inside a deposit, so each teller runs its 50 deposits in one go. Stackful grants the baton twice and gets it back twice, as each thread finishes. Green calls send on each task, hits g1_teller's trailing yield after all 50 deposits, and counts one switch each.
• ACT 2, stackful: 102. 2 tellers × 50 deposits × 1 suspension = 100 baton returns, plus the 2 returns that happen when each thread exits.
• ACT 3, stackless: 100. The same 100 suspensions. Green.switches does not count the final send that raises StopIteration, so there is no + 2.

Same interleaving, same number of switches, same answer. The only thing that differs between ACT 2 and ACT 3 is how many source files had to change.

6.2 Where 150 comes from

Both schedulers are round-robin, and the suspension sits at a fixed point in io_read, so the tasks march in lockstep. Every teller reads bank["acct"], every teller suspends, every teller then writes v + 1 — the same v, and therefore the same v + 1. The last writer wins and the balance has advanced by exactly one, whether two tellers or eight were in the round.

So final = START + deposits. With START = 100 and deposits = 50: 150, and 2 × 50 − 50 = 50 increments lost — half of them.

The tellers column is the part worth staring at. At 4 tellers the program performs 200 increments and the balance still moves by 50. Adding concurrency added exactly zero correct work. This is not "throughput scaled sublinearly"; it is a program whose useful output is independent of how much of it you run.

6.3 The load-bearing line, and the inert one

The load-bearing line: suspend() moved by one position inside sf_io_read. 200 → 150. It is the same function either way, it suspends the same number of times either way, and the number of tasks, deposits and context switches are unchanged. The only thing that moved is whether the suspension falls between the read and the write.

This is the best line in the toy, because the two variants are indistinguishable to every caller and to every reviewer who is not reading the library's body. io_read suspends: that fact, which is the only fact an await would have told you, is true in both. What matters is a detail one level below the interface.

The inert line: the colouring. Four frames edited, 150 before and 150 after. It is worth being blunt about what this rules out. Colouring is not a correctness mechanism, does not serialise anything, does not shorten the critical section, and does not prevent the interleaving. It writes the fact of a possible switch into the source at every level, and stops there.

6.4 Certain against rare

This is a claim about real runtimes, so it is measured against real ones — real asyncio, real threading, not the toy.

Real asyncio reproduces 150 exactly, on every trial. The toy is not inventing its model: await asyncio.sleep(0) between the read and the write of a two-task gather is the same program, and it produces the same number.

Panel B is deliberately noisy, and its noise is the finding. Preemption survived 50,000 deposits — a thousand times the workload panel A used — without losing a single update. It took a padded window to make it fail at all, and even then on 2 of 5 trials rather than 5. Only at 200,000 deposits did it fail every time. Row by row this table is different on every run of the demo; the row that has not moved across any run behind this page is the first one, 50 deposits, pad 0, 0 wrong, which is the row that matches panel A.

That asymmetry is the whole point. The cooperative failure is total (50% of increments), reproducible (20/20), and derivable in advance from the source (§6.2). The preemptive failure needs the OS to interrupt a thread inside a window of a few bytecodes — CPython checks for a thread switch every 5 ms by default, and 100 iterations of a tight loop finish long before that — so it missed 20 times out of 20 at the workload where the cooperative version was certain.

The received wisdom is "cooperative concurrency is safer, because you know where you yield". Both halves are true and the conclusion is backwards. You do know where you yield. That is exactly why the failure is total and reproducible rather than a one-in-a-million heisenbug. It is not a race you will catch in staging, because it is not a race: it is the only behaviour the program has.

The narrower, still-true version of the folklore: cooperative scheduling eliminates data races — no torn reads, no half-written objects, no need for a mutex around a dict. It does nothing whatever about invariant races, which is what a lost update is.

6.5 The limit of the safety net

§6.1 said the stackless runtime "refuses to run". That claim is false as stated, and here is the counterexample.

The type error only fires because g2_deposit did arithmetic. Two extremely ordinary things a caller might do instead:

• Forward it. log.append(io_read()), return self._fetch(k), results[key] = load(key). The generator or coroutine object is stored, passed on, serialised, cached — and never runs. The failure surfaces somewhere else entirely, as missing data.
• Truth-test it. if user_exists(): deny(). bool() of an unstarted generator and of an un-awaited coroutine is unconditionally True, so a function that was going to answer False now answers True, silently, forever. The demo's test_bool_of_an_unawaited_coroutine_is_unconditionally_true pins this with a coroutine whose body is literally return False.

Python's only defence is a RuntimeWarning — coroutine '...' was never awaited — emitted by the garbage collector, at an unpredictable time, often long after the request that caused it has been answered, and only for async def, never for a plain generator. It is a real safety net and it has large holes in it.

So the honest form of the headline is: the stackless runtime refuses to run where the caller consumes the value, and fails silently where it does not. That is still better than the stackful column, which has no signal at any call site. It is not the categorical guarantee "colouring makes it a compile error" suggests.

6.6 What a task costs

This is the reason anybody tolerates any of the above.

Three numbers and one derivation.

192.5 B/task is a suspended one-frame generator, measured with tracemalloc, which sees Python heap allocations exactly. 1176.5 B/task is one of this toy's own tasks — a g3_teller suspended five yield from levels down, so five live generator objects. 1176.5 / 5 = 235.3 bytes per frame, and the two measurements agree to within the size of a frame's locals. That is the arithmetic behind the number, and it is also a fact about the stackless design worth keeping: a stackless task's memory is proportional to how deep it was when it suspended, because the suspended chain is the stack. Colouring is not only a source-code tax.

38,789 B/task is a parked OS thread, measured by RSS delta because a thread's stack is not a Python allocation and tracemalloc cannot see it. It is resident memory, not reserved: RLIMIT_STACK on this machine is 8,372,224 bytes, so each thread reserves 8 MB of address space and touches about 38 KB of it.

16,383 is where threading stopped, with RuntimeError: can't start new thread. It was 16,383 on every run — 2^14 − 1, a hard macOS limit rather than a memory exhaustion, since 16,383 × 38 KB is well under this machine's RAM. Green tasks hit no limit at 100,000, which is where the demo stops asking.

These are the only timing- and memory-derived numbers on this page. They are one machine's, on one run. Across four runs of the panel the tracemalloc figures were byte-identical every time, the OS-thread ceiling was exactly 16,383 every time, and the RSS figure moved between 38,789 and 39,002 B — a spread of 0.5%.

6.7 The boundaries — where the effect vanishes

Three of them, all measured.

Boundary 1 — one teller. tellers=1 gives final=150 and lost=0: with one task the "correct" answer is 150, because 50 deposits were performed. Nothing interleaves, so the suspension inside the critical section is harmless. The effect needs at least two tasks sharing the state, which is the same condition as any lost update.

Boundary 2 — the suspension outside the critical section. From §6.3: suspend(); v = bank[acct] gives 200. The suspension may stay; only its position matters. A library that suspends before touching shared state, or after it has finished with it, is free.

Boundary 3 — call depth 0, and this is the important one. At D = 0 the suspending code is the task's own body. Nothing is forced to change in either runtime; the uncoloured stackless column runs perfectly happily, because there is no un-coloured caller to be silent about anything. The two runtimes are, at that depth, the same tool with different spelling.

Every toy example of async code is written at D = 0. async def main(): await fetch(url) has no intermediate frames. That is precisely why the trade looks free in tutorials, and why the argument between goroutines and async/await only starts to exist at D ≥ 1 — inside somebody's ORM, HTTP client, retry decorator or template renderer, where the call stack between your task and the socket is fifteen frames deep and none of them are yours.

The depth table is generated and executed, not asserted: chain() in §5.7 writes each program, and test_colouring_costs_exactly_D_edits_at_depth_D runs all five depths in all three styles.

6.8 Pinned by tests

python3 test_runtimes.py

test_real_threads_are_wrong_on_0_of_20_trials is the only assertion in this repo that is a probability rather than a certainty, which is itself §6.4's lesson. It passed on eight consecutive runs of the suite while writing this page.

7. Design decisions and roads not taken

7.1 What this toy owns, and what mini-asyncio owns

These two toys share a scheduler shape and must not be read as the same lesson.

mini-asyncio is about when a task resumes. It takes stacklessness as given and never mentions it. Its subject is the ready queue and the timer heap: a task that asked for a 1000 ms tick gets one every 1400 ms, and the loop's own instrumentation reports zero lateness. Its result is measured in milliseconds and its closed form is (⌈P/R⌉ + hops)·R.

This toy is about where a task may suspend. It has no timers, no clock, no lateness and no queue arithmetic — deliberately, because that boundary has to stay clean. Its result is measured in lost increments and edited frames, and its closed form is final = START + deposits. Nothing here depends on how long anything took.

The two questions are independent, and each has a runtime that answers it and ignores the other. A goroutine is stackful and preemptive since Go 1.14; a Java virtual thread is stackful and cooperative. This toy's Stackful is stackful and cooperative, which is the combination that isolates the variable it cares about.

work-stealing-queue is a third question again — which worker runs a task — and is untouched by both.

7.2 A baton over OS threads, not real preemption

Stackful could have used bare threads and let the OS interleave them. It hands a baton instead, so exactly one thread runs at a time and switches only at suspend().

That is not a simplification for its own sake; it is what makes the comparison mean anything. With real preemption the stackful column produces a different number nearly every run. Five trials of demo.preempt_trial at 2 × 200,000 deposits, expecting 400,100, gave [284384, 329477, 315982, 370107, 356466] — five distinct wrong answers. A page built on that would be comparing "cooperative, deterministic" against "preemptive, random", which is two variables at once. With the baton, both columns run the same interleaving, produce the same 150, and the only difference left is the suspension point.

The cost of the choice is that Stackful is not what a production stackful runtime looks like. §6.4 pays that back by running the real preemptive version separately, where its randomness is the finding rather than the noise.

7.3 Generators, not greenlet or async def

Three candidates for the stackless column, and two lost.

greenlet is the obvious tool — it gives CPython genuine stackful coroutines by switching C stacks, and gevent is built on it. It is out because it is a third-party C extension (the repo's toys are stdlib-only), and more importantly because using it would delete the toy: with greenlet both columns are stackful and there is nothing left to compare.

async def would look more modern, and §6.4 uses real coroutines to check the claim. It is not the toy's stackless runtime because a coroutine cannot yield a value to its driver without an awaitable protocol, so the toy would need an __await__ shim purely for appearances — and because yield from makes the colouring visible as a chain, which is the thing being counted. Every conclusion transfers: await is yield from with a keyword.

sys.setrecursionlimit games / trampolines. A trampoline (return a thunk, let the scheduler call it) is a third way to get suspension at depth without a stack. It is absent because it colours harder than yield from — every frame must return a thunk rather than a value — and would make the toy about CPS, not about the choice it is examining.

7.4 A bank, not a socket

The workload is a lost update on an integer, which is a database example, not a concurrency-runtime example. That is on purpose. A socket workload would need I/O, a selector and a reason for the reader to trust that the toy's io_read resembles a real one; the bank needs none of that, and the correct answer is a number a reader can verify in their head.

The cost is that the failure looks like a database problem, and readers may file it under "use a transaction". §9's last question is aimed squarely at that reflex.

7.5 The context-switch ratio, measured and dropped

The obvious fifth number for §6.6 is what a switch costs each way. It is not on this page, and the omission is deliberate.

Measured six times on this machine (200,000 generator resumptions, 20,000 semaphore baton handoffs between two threads, per run): the generator send was stable at 29.9–38.8 ns; the OS-thread handoff came out at 6,913, 6,989, 7,072, 7,075, 8,936 and 9,359 ns. That is a quotable ratio anywhere between 222× and 312× depending on which run you print.

A number whose second significant figure depends on what else the laptop was doing is not a result, it is a mood. The repo's rule is that a reader must be able to re-derive every number on the page; a 40% spread makes that impossible, so the number does not ship and there is no switch-cost code in demo.py. What can be said and reproduced is the memory ratio and the ceiling in §6.6, both of which were stable to under 1%.

7.6 Roads not taken

• A lock. Wrapping sf_deposit in a mutex fixes the bug and ends the toy: it makes both columns return 200 and says nothing about suspension points. The interesting question — how would you know you needed one? — is §9's territory, and the answer differs between the two runtimes, which is the only reason the lock is worth mentioning at all.
• Channels or a select. A real green-thread runtime ships them. They are a communication mechanism layered on the suspension point, and this toy is about the point.
• Cancellation. The hardest thing a real stackful runtime does, because a task's stack has to be unwound from outside. Omitting it lets the stackful column look simpler than it is; §8 says so.
• Stack copying / growable stacks. The mechanism that makes real stackful runtimes cheap, and the one thing this toy fundamentally cannot demonstrate in Python. §8.1.
• A work-stealing or multi-core scheduler. Both runtimes are strictly one-task-at-a-time. Parallelism would reintroduce genuine data races and drown the signal.

8. What's simplified vs. the real thing

8.1 The memory ratio is the price of OS threads, not of stackfulness

This is the disclosure that matters most, because it is the one place the toy could mislead you into a wrong conclusion about real systems.

§6.6 measures 38,789 bytes per stackful task against 192.5 per green one, and it would be easy to read that as "stackful tasks are 200× more expensive". They are not. That is the price of an OS thread, which is the only stackful task CPython can build.

Go starts a goroutine on a 2 KB stack — stackMin = 2048 in src/runtime/stack.go — and grows it by allocating a bigger one and copying the old one into it, adjusting every pointer that referred to the old stack as it goes. Java's virtual threads do something comparable, unmounting a continuation's stack chunks onto the heap while it is parked. Both are stackful, both suspend from arbitrary depth, and both cost a few hundred bytes for a task that has not gone deep.

What that requires is a runtime that knows where every pointer into a stack lives — precise stack maps, its own calling convention, and a garbage collector that cooperates. CPython has none of those; its frames are entangled with C stack frames from every extension module on the stack. There is no supported way to relocate one. That is why Project Loom took a decade, and why greenlet has to do it by copying raw C stack segments and hoping.

So the honest reading of §6.6 is narrower than it looks: in Python, choosing stackful means choosing OS threads, and that is what costs 38 KB and caps you at 16,383. In Go or on the JVM, the memory column of this comparison largely disappears and only the source-code column — §6.7's D edits — remains.

8.2 The other simplifications

• No preemption in either runtime. Real goroutines have been asynchronously preemptible since Go 1.14, which means a stackful task in Go can lose the CPU at a point nobody wrote down. That is strictly worse for the invariant in §6.2 and strictly better for latency. This toy's stackful column is cooperative so that the two columns differ in one variable only.
• No I/O. io_read reads a dict. A real one would register with a selector and suspend until readable, and the suspension would last a variable, data-dependent time. Nothing in §6.2 depends on the duration, so the fiction is free — but it does mean the toy cannot show the good case, where suspension inside a slow call is exactly what you want.
• No cancellation, no timeouts, no structured concurrency. A task here runs until it returns. Cancelling a stackful task means unwinding a stack you are not running on, which is the hardest part of a real implementation and is the reason greenlet and Loom both had to define what happens to a parked task that is killed.
• One scheduler, one thread of execution. No parallelism, so no genuine data races and no memory model. A real runtime multiplexes green tasks across a pool of OS threads (GOMAXPROCS, Loom's ForkJoinPool), which reintroduces every problem this toy suppressed and adds work-stealing on top.
• WHERE as a global. A real library either has the suspending line or does not; reading a module flag inside io_read is a testing seam that no production code would carry. It exists so §6.3's counterfactual is a parameter rather than a fourth copy of the workload.
• No Task object, no result, no exception propagation. A task that raises inside Green.run escapes into the scheduler; inside Stackful it would kill the thread's body and release the baton via the finally, which is more graceful than it deserves to be. Real runtimes deliver an exception to whoever joins the task.
• Green re-queues unconditionally. There is no notion of a task waiting on anything — every suspension means "ready again immediately". That is asyncio.sleep(0), not await socket.read(), and it is why the toy has no need for mini-asyncio's timer heap.

9. Check yourself

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

10. Further reading

• What Color is Your Function? — Bob Nystrom, 2015. The essay that named the problem this toy measures. Read it for the argument; this page is the part it does not do, which is putting an integer on the tax and then checking whether paying it buys correctness.
• PEP 380 — Syntax for Delegating to a Subgenerator — yield from, which is the four edits in §5.6. Its rationale section is explicit that the motivation was exactly this: letting a generator's suspension pass through intermediate frames without hand-written forwarding loops.
• PEP 342 — Coroutines via Enhanced Generators — where send() comes from, and therefore why Green.run is nine lines.
• PEP 492 — Coroutines with async and await syntax — how the yield from chain in §5.6 became a keyword. Worth reading beside PEP 380 to see that await added syntax and a type, not a mechanism.
• go/src/runtime/stack.go — stackMin = 2048, and below it the copying stack grower. This is the code §8.1 says CPython cannot have: copystack walks every frame adjusting pointers into the old stack.
• Go FAQ — Why goroutines instead of threads? — the language's own two-paragraph answer, including the multiplexing onto OS threads that makes §6.6's memory column vanish.
• JEP 444 — Virtual Threads — Loom, shipped. Its "Motivation" is §2 of this page written by people who had to implement it, and its explicit goal of not colouring the API is the stackful column's argument in one sentence.
• State of Loom — Ron Pressler on why this took ten years: continuations, stack chunks, and the parts of the JVM that had to change. The best available answer to "why can't Python just do this".
• PostgreSQL 13.2 — Transaction Isolation — the lost update in §6.2, from the database side, including the SELECT FOR UPDATE and serializable answers that a green-thread runtime does not give you.
• greenlet — stackful coroutines for CPython, by copying C stack segments. The road not taken in §7.3, and worth reading for its list of things that break.
• Coroutines and Tasks — the stdlib page, for the RuntimeWarning: coroutine ... was never awaited that §6.5 shows arriving too late to help.