Programming in Lua : 9.1

This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.
The fourth edition targets Lua 5.3 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.

Programming in Lua

Part I. The Language Chapter 9. Coroutines

9.1 – Coroutine Basics

Lua offers all its coroutine functions packed in the coroutine table. The create function creates new coroutines. It has a single argument, a function with the code that the coroutine will run. It returns a value of type thread, which represents the new coroutine. Quite often, the argument to create is an anonymous function, like here:

    co = coroutine.create(function ()
           print("hi")
         end)
    
    print(co)   --> thread: 0x8071d98

A coroutine can be in one of three different states: suspended, running, and dead. When we create a coroutine, it starts in the suspended state. That means that a coroutine does not run its body automatically when we create it. We can check the state of a coroutine with the status function:

    print(coroutine.status(co))   --> suspended

The function coroutine.resume (re)starts the execution of a coroutine, changing its state from suspended to running:

    coroutine.resume(co)   --> hi

In this example, the coroutine body simply prints "hi" and terminates, leaving the coroutine in the dead state, from which it cannot return:

    print(coroutine.status(co))   --> dead

Until now, coroutines look like nothing more than a complicated way to call functions. The real power of coroutines stems from the yield function, which allows a running coroutine to suspend its execution so that it can be resumed later. Let us see a simple example:

    co = coroutine.create(function ()
           for i=1,10 do
             print("co", i)
             coroutine.yield()
           end
         end)

Now, when we resume this coroutine, it starts its execution and runs until the first yield:

    coroutine.resume(co)    --> co   1

If we check its status, we can see that the coroutine is suspended and therefore can be resumed again:

    print(coroutine.status(co))   --> suspended

From the coroutine's point of view, all activity that happens while it is suspended is happening inside its call to yield. When we resume the coroutine, this call to yield finally returns and the coroutine continues its execution until the next yield or until its end:

    coroutine.resume(co)    --> co   2
    coroutine.resume(co)    --> co   3
    ...
    coroutine.resume(co)    --> co   10
    coroutine.resume(co)    -- prints nothing

During the last call to resume, the coroutine body finished the loop and then returned, so the coroutine is dead now. If we try to resume it again, resume returns false plus an error message:

    print(coroutine.resume(co))
    --> false   cannot resume dead coroutine

Note that resume runs in protected mode. Therefore, if there is any error inside a coroutine, Lua will not show the error message, but instead will return it to the resume call.

A useful facility in Lua is that a pair resume-yield can exchange data between them. The first resume, which has no corresponding yield waiting for it, passes its extra arguments as arguments to the coroutine main function:

    co = coroutine.create(function (a,b,c)
           print("co", a,b,c)
         end)
    coroutine.resume(co, 1, 2, 3)    --> co  1  2  3

A call to resume returns, after the true that signals no errors, any arguments passed to the corresponding yield:

    co = coroutine.create(function (a,b)
           coroutine.yield(a + b, a - b)
         end)
    print(coroutine.resume(co, 20, 10))  --> true  30  10

Symmetrically, yield returns any extra arguments passed to the corresponding resume:

    co = coroutine.create (function ()
           print("co", coroutine.yield())
         end)
    coroutine.resume(co)
    coroutine.resume(co, 4, 5)     --> co  4  5

Finally, when a coroutine ends, any values returned by its main function go to the corresponding resume:

    co = coroutine.create(function ()
           return 6, 7
         end)
    print(coroutine.resume(co))   --> true  6  7

We seldom use all these facilities in the same coroutine, but all of them have their uses.

For those that already know something about coroutines, it is important to clarify some concepts before we go on. Lua offers what I call asymmetric coroutines. That means that it has a function to suspend the execution of a coroutine and a different function to resume a suspended coroutine. Some other languages offer symmetric coroutines, where there is only one function to transfer control from any coroutine to another.

Some people call asymmetric coroutine semi-coroutines (because they are not symmetrical, they are not really co). However, other people use the same term semi-coroutine to denote a restricted implementation of coroutines, where a coroutine can only suspend its execution when it is not inside any auxiliary function, that is, when it has no pending calls in its control stack. In other words, only the main body of such semi-coroutines can yield. A generator in Python is an example of this meaning of semi-coroutines.

Unlike the difference between symmetric and asymmetric coroutines, the difference between coroutines and generators (as presented in Python) is a deep one; generators are simply not powerful enough to implement several interesting constructions that we can write with true coroutines. Lua offers true, asymmetric coroutines. Those that prefer symmetric coroutines can implement them on top of the asymmetric facilities of Lua. It is an easy task. (Basically, each transfer does a yield followed by a resume.)