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|
Lua offers all its coroutine functions packed in 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
which represents the new coroutine.
Quite often, the argument to
create is an anonymous function,
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
print(coroutine.status(co)) --> suspendedThe function
coroutine.resume(re)starts the execution of a coroutine, changing its state from suspended to running:
coroutine.resume(co) --> hiIn 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
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
coroutine.resume(co) --> co 1If we check its status, we can see that the coroutine is suspended and therefore can be resumed again:
print(coroutine.status(co)) --> suspendedFrom 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
yieldfinally 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 nothingDuring 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,
resumereturns false plus an error message:
print(coroutine.resume(co)) --> false cannot resume dead coroutineNote that
resumeruns 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
A useful facility in Lua is that
a pair resume-yield can exchange data between them.
resume, which has no corresponding
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 3A call to
resumereturns, after the true that signals no errors, any arguments passed to the corresponding
co = coroutine.create(function (a,b) coroutine.yield(a + b, a - b) end) print(coroutine.resume(co, 20, 10)) --> true 30 10Symmetrically,
yieldreturns any extra arguments passed to the corresponding
co = coroutine.create (function () print("co", coroutine.yield()) end) coroutine.resume(co) coroutine.resume(co, 4, 5) --> co 4 5Finally, when a coroutine ends, any values returned by its main function go to the corresponding
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.)
|Copyright © 2003–2004 Roberto Ierusalimschy. All rights reserved.|