Coroutines: Cooperative Multitasking

A coroutine is an independent thread of execution that you can pause and resume by hand, unlike OS threads, only one coroutine (or the main program) ever runs at a time, so there's no race condition to worry about.

Creating and resuming a coroutine

local co = coroutine.create(function(a, b)
  print("start", a, b)
  local c = coroutine.yield(a + b) -- pauses here, returns a + b to the resumer
  print("resumed with", c)
  return "done"
end)

print(coroutine.resume(co, 1, 2)) -- true  3   (prints "start 1  2" first)
print(coroutine.resume(co, 10))    -- true  done  (prints "resumed with  10" first)
print(coroutine.status(co))         -- dead

• coroutine.create(fn) builds a coroutine without running it yet.
• coroutine.resume(co, ...) starts/continues it, passing ... in as arguments (either to the function itself, the first time, or as coroutine.yield's return value on later resumes).
• coroutine.yield(...) pauses the coroutine and hands ... back to whoever called resume.
• coroutine.status(co) reports "suspended", "running", "normal", or "dead".

A generator built on coroutines

local function numberGenerator(limit)
  return coroutine.wrap(function()
    for i = 1, limit do
      coroutine.yield(i)
    end
  end)
end

for n in numberGenerator(5) do
  print(n) -- 1 2 3 4 5, one per iteration
end

coroutine.wrap is coroutine.create plus automatic resume calls, wrapped in a plain function you can call directly (or use in a for ... in loop), it's the idiomatic way to build a lazy generator/iterator in Lua.