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.
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)) --> deadresume, 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.resumereturnstrue, results...on success orfalse, erron error, structurally similar topcall.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
forloops, and cooperative schedulers for async I/O frameworks.
Practice what you learned
1. What state is a coroutine in immediately after `coroutine.create(f)` is called?
2. What does `coroutine.yield(x)` do?
3. How does error handling differ between coroutine.resume and coroutine.wrap?
4. Why are coroutines well-suited for building custom iterators?
Was this page helpful?
You May Also Like
Error Handling in Lua (pcall/error)
Learn how Lua signals and catches errors using error(), pcall(), and xpcall(), instead of try/catch exceptions.
Modules and require
Learn how Lua organizes reusable code into modules with the require function, package.path, and the standard return-a-table pattern.
Object-Oriented Lua
Learn how Lua uses tables, functions, and metatables to build objects, methods, and encapsulation without a built-in class system.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics