Coroutines in Lua

Analogy categoryAnalogies

What a Coroutine Is

A coroutine is an independent line of execution with its own stack, local variables, and instruction pointer, but unlike an OS thread, only one coroutine (or the main program) ever runs at a time — there is no preemption or parallelism, only cooperative switching. You create one with coroutine.create(f), which returns a coroutine object in the "suspended" state without running any of f's code yet; execution only begins when you call coroutine.resume() on it.

🏏

Cricket analogy: A batter waiting at the non-striker's end is fully capable of batting but paused until the strike rotates to them, mirroring a coroutine sitting suspended until resume() hands it control.

lua

local co = coroutine.create(function(a)
  print("start", a)
  local b = coroutine.yield(a + 1)
  print("resumed with", b)
  local c = coroutine.yield(b + 1)
  print("resumed with", c)
  return "done"
end)

print(coroutine.resume(co, 10))  --> start 10 \n true 11
print(coroutine.resume(co, 20))  --> resumed with 20 \n true 21
print(coroutine.resume(co, 30))  --> resumed with 30 \n true done
print(coroutine.status(co))      --> dead

resume, yield, and Passing Values

coroutine.resume(co, ...) starts or continues a suspended coroutine, passing ... as either the initial function arguments (first resume) or as the return value of the coroutine.yield() call that paused it (subsequent resumes). Inside the coroutine, coroutine.yield(...) pauses execution and passes ... back out as extra return values of the resume() call that triggered it. resume always returns true, ... on success or false, errorMessage if the coroutine raised an error, similar in shape to pcall.

🏏

Cricket analogy: A captain calling for a strategy huddle mid-over, handing instructions to a bowler who then returns to bowling with new information, mirrors resume() passing data in and yield() passing data back.

Coroutine States and coroutine.wrap

A coroutine is always in one of four states, queryable via coroutine.status(co): "suspended" (paused, ready to resume), "running" (currently executing — only true from the coroutine's own perspective), "normal" (active but has resumed another coroutine and is waiting on it), or "dead" (finished, either by returning normally or by erroring). coroutine.wrap(f) is a convenience alternative to coroutine.create that returns a plain function instead of a coroutine object; calling that function resumes the coroutine directly and, unlike resume, propagates errors by raising them rather than returning false, err — making wrap ideal for generator-style iterators used in for loops.

🏏

Cricket analogy: A bowler's over status cycling through 'about to bowl', 'currently bowling', 'waiting at mid-off while a fielder throws', and 'over completed' mirrors a coroutine's suspended/running/normal/dead states.

Unlike coroutine.resume, coroutine.wrap does NOT return a success boolean — if the wrapped coroutine errors, the error propagates as a normal Lua error from the wrapper function call itself. This means code using coroutine.wrap should be wrapped in pcall if you need to handle errors gracefully, rather than checking a return value.

Practical Use: Generators and Iterators

The most common real-world use of coroutines is building custom iterators for Lua's generic for loop: a function using coroutine.wrap can yield one value per iteration, letting you write complex traversal logic (like walking a nested tree structure) imperatively with loops and recursion, instead of manually managing state between calls. Because each yield preserves the coroutine's entire call stack, you can yield from deep inside nested function calls, which is something a simple stateful closure-based iterator cannot do without significant restructuring.

🏏

Cricket analogy: A ball-by-ball live commentary feed that yields one delivery's outcome at a time as the over progresses, rather than dumping the entire innings summary at once, mirrors a coroutine-based generator.

Because coroutines yield from arbitrary call depth, they're also used to implement cooperative task schedulers and async-style I/O in frameworks like Copas and OpenResty's Lua/Nginx integration, where a coroutine yields whenever it would block on a socket, letting an event loop resume it once data is ready.

A coroutine is a cooperative (non-preemptive) line of execution with its own stack, created via coroutine.create(f) in a suspended state.
coroutine.resume(co, ...) starts/continues execution; coroutine.yield(...) pauses it and passes values back to the resumer.
resume returns true, results... on success or false, err on error, structurally similar to pcall.
coroutine.status(co) reports one of four states: suspended, running, normal, or dead.
coroutine.wrap(f) returns a plain callable function instead of a coroutine object, but propagates errors instead of returning a success flag.
The most common practical use is building generator-style iterators for for loops, and cooperative schedulers for async I/O frameworks.