Bonus: Coroutines

Optional — the most distinctively Lua thing in the language, and the one with no real equivalent in most others.

The Idea

Every function you have written runs from top to bottom and then stops. A coroutine is a function that can pause in the middle, hand control back, and later carry on from exactly where it left off — with all its local variables still in place.

local function sequence()
  print("step 1")
  coroutine.yield()
  print("step 2")
  coroutine.yield()
  print("step 3")
end

local co = coroutine.create(sequence)

print("status:", coroutine.status(co))
coroutine.resume(co)
coroutine.resume(co)
coroutine.resume(co)
print("status:", coroutine.status(co))

status:  suspended
step 1
step 2
step 3
status:  dead

Three functions do all the work:

coroutine.create wraps a function up. It does not run it — note that nothing printed until the first resume.
coroutine.resume starts it, or continues it from its last pause.
coroutine.yield pauses from the inside and returns control to whoever resumed.

This is not a thread. Nothing runs at the same time as anything else, there is no scheduler, and you never need a lock. Control moves between two places, and only one of them is ever running. That is why coroutines are easy to reason about and threads are not.

The shortcut: wrap

coroutine.wrap hands you a plain function instead of a coroutine object. Call the function to resume it, and whatever it yields comes straight back.

local squares = coroutine.wrap(function()
  for i = 1, 4 do
    coroutine.yield(i * i)
  end
end)

print(squares())
print(squares())

1
4

Look at what that is. A function you can keep calling, which remembers where it got to and produces the next value. That is exactly the iterator contract from Activity 1.8 — so a wrapped coroutine can drive a for ... in loop directly, and when it finishes it returns nil and the loop stops on its own.

The difference from a closure iterator is what you can express. A closure has to reconstruct its position from stored variables every call; a coroutine just keeps standing where it was. For walking a nested structure, that is the difference between a bookkeeping exercise and a recursive function with a yield in it.

wrap has one cost: create plus resume reports errors by returning false, like pcall, whereas a wrapped one raises them at you. Use wrap for iterators and create when you want to check the status.

Why a game programmer cares

Here is the problem coroutines solve. A game runs one function per frame, sixty times a second. You want to write: open the door, wait two seconds, sound the alarm, wait one more, cut the lights.

Without coroutines that becomes a state machine — a phase variable, a timer, and a growing chain of elseif — and the sequence you wanted is scattered across it. With coroutines you write the sequence.

local function wait(seconds)
  local elapsed = 0
  while elapsed < seconds do
    elapsed = elapsed + coroutine.yield()
  end
end

local cutscene = coroutine.create(function()
  print("Door opens")
  wait(2)
  print("Alarm sounds")
  wait(1)
  print("Lights out")
end)

for frame = 1, 8 do
  if coroutine.status(cutscene) ~= "dead" then
    coroutine.resume(cutscene, 0.5)
  end
end

Door opens
Alarm sounds
Lights out

The loop stands in for a game's frames, each one worth half a second. The value passed to resume comes back out of yield inside the coroutine, which is how wait learns how much time went by. Values travel both directions.

In Unit 2 the frame loop is love.update(dt) and you would resume with the real dt. The cutscene function would not change at all.

Two things to remember. A dead coroutine cannot be resumed — check the status or you get a false and a "cannot resume dead coroutine" message. And you cannot yield from inside a normal function called by C code, which in practice means avoid yielding from inside a table.sort comparison or a metamethod.

Build

Start a fresh main.lua.

Task 1: Pause and continue

Write a function that prints three steps with a coroutine.yield() between each.
Create a coroutine from it and print the status before resuming.
Resume three times, then print the status again.
Confirm nothing printed until the first resume. Creating is not running.

1
-- main.lua - coroutines
2

3
local function sequence()
4
  print("step 1")
5
  coroutine.yield()
6
  print("step 2")
7
  coroutine.yield()
8
  print("step 3")
9
end
10

11
local co = coroutine.create(sequence)
12

13
print("status:", coroutine.status(co))
14
coroutine.resume(co)
15
coroutine.resume(co)
16
coroutine.resume(co)
17
print("status:", coroutine.status(co))

status:  suspended
step 1
step 2
step 3
status:  dead

Task 2: A generator, then a loop

Use coroutine.wrap to make something that yields square numbers, and call it twice.
Then make a second one and drive it with for n in gen do.
Note that you never wrote a stop condition. The coroutine finished, returned nil, and the loop ended.

1
-- main.lua - coroutines
2

3
local function sequence()
4
  print("step 1")
5
  coroutine.yield()
6
  print("step 2")
7
  coroutine.yield()
8
  print("step 3")
9
end
10

11
local co = coroutine.create(sequence)
12

13
print("status:", coroutine.status(co))
14
coroutine.resume(co)
15
coroutine.resume(co)
16
coroutine.resume(co)
17
print("status:", coroutine.status(co))
18

19
local squares = coroutine.wrap(function()
20
  for i = 1, 4 do
21
    coroutine.yield(i * i)
22
  end
23
end)
24

25
print(squares())
26
print(squares())
27

28
local gen = coroutine.wrap(function()
29
  for i = 1, 3 do coroutine.yield(i) end
30
end)
31

32
for n in gen do
33
  print("got", n)
34
end

status:  suspended
step 1
step 2
step 3
status:  dead
1
4
got  1
got  2
got  3

Task 3: A timed sequence

Write wait(seconds) that keeps yielding until enough time has been handed to it.
Write a cutscene coroutine that prints three lines with waits between them.
Drive it with a loop of eight frames, each worth 0.5, skipping the resume once it is dead.
Read the cutscene function on its own. It is a straight list of instructions with pauses in it — no state variable, no phase counter. That is the whole argument for coroutines.

1
-- main.lua - coroutines
2

3
local function sequence()
4
  print("step 1")
5
  coroutine.yield()
6
  print("step 2")
7
  coroutine.yield()
8
  print("step 3")
9
end
10

11
local co = coroutine.create(sequence)
12

13
print("status:", coroutine.status(co))
14
coroutine.resume(co)
15
coroutine.resume(co)
16
coroutine.resume(co)
17
print("status:", coroutine.status(co))
18

19
local squares = coroutine.wrap(function()
20
  for i = 1, 4 do
21
    coroutine.yield(i * i)
22
  end
23
end)
24

25
print(squares())
26
print(squares())
27

28
local gen = coroutine.wrap(function()
29
  for i = 1, 3 do coroutine.yield(i) end
30
end)
31

32
for n in gen do
33
  print("got", n)
34
end
35

36
local function wait(seconds)
37
  local elapsed = 0
38
  while elapsed < seconds do
39
    elapsed = elapsed + coroutine.yield()
40
  end
41
end
42

43
local cutscene = coroutine.create(function()
44
  print("Door opens")
45
  wait(2)
46
  print("Alarm sounds")
47
  wait(1)
48
  print("Lights out")
49
end)
50

51
for frame = 1, 8 do
52
  if coroutine.status(cutscene) ~= "dead" then
53
    coroutine.resume(cutscene, 0.5)
54
  end
55
end

Challenge (Optional)

Change the frame size to 0.25 and confirm the cutscene still produces the same three lines, just over more frames. The sequence is written in seconds, not frames, which is the property you want.
Make wait return how much it overshot by, and have the caller print it.
Write a coroutine that walks a nested table and yields every value it finds at any depth, then drive it with for v in .... Recursion plus yield makes this about six lines; try it as a closure iterator afterwards and see how much harder it gets.

Check Your Work

status:  suspended
step 1
step 2
step 3
status:  dead
1
4
got  1
got  2
got  3
Door opens
Alarm sounds
Lights out

Three lines from a function that paused twice, across eight frames it knew nothing about.

Previous Next: String Patterns