Lua Coroutines - Lua (programming language)

What are Lua Coroutines?


Coroutines in Lua are mutual in nature which allows two or more methods to execute in a restricted manner. With coroutines, at any given point of time, only one coroutine will run and this running coroutine will suspend its execution when it explicitly requests to be suspended.

Above definition may be unclear. Let’s assume there are two methods, one main program method and a coroutine method. When coroutine method is called using resume function, it will start executing and when yield function is called, it will suspend executing. Again the same coroutine will continue executing with another resume function call from where it was suspended. This process continues till the end of execution of the coroutine method.

Functions Available in Coroutines

Below table lists all the available functions for coroutines in Lua and their corresponding use.


Method & Purpose


coroutine.create (f)

This will create a new coroutine with a function f and returns an object of type "thread".


coroutine.resume (co [, val1, ...])

This will resume the coroutine co and it passes the parameters if any. It will return the status of operation and optional other return values.


coroutine.running ()

This will return the running coroutine or nil if called in the main thread.


coroutine.status (co)

This will return one of the values from running, normal, suspended or dead based on the state of the coroutine.


coroutine.wrap (f)

Like coroutine.create, coroutine.wrap function will also create a coroutine, but instead of returning the coroutine itself, it will return a function which, when called, will resume the coroutine.


coroutine.yield (...)

This will suspend the running coroutine. Parameter passed to this method acts as additional return values to the resume function.


Let's look at an example to understand the concept of coroutines.

When you run the above program, below output will be displayed.

What Does the Above Example Do?

As mentioned earlier, resume function is used for starting the operation and yield function is used for stoping the operation. Also, you can observe multiple return values are received by resume function of coroutine.

  • First, create a coroutine and assign it to a variable name co and then the coroutine will take in two variables as its parameters.
  • Whenthe first resume function is called, values 3 and 2 will be retained in the temporary variables value1 and value2 till the end of coroutine method.
  • To get better understanding on this, we have used a tempvar3, which is 10 initially and it gets updated to 13 and 16 by the subsequent calls of the coroutines as value1 is retained as 3 throughout the execution of the coroutine.
  • First coroutine.yield will return two values 4 and 3 to the resume function, which we get by updating the input params 3 and 2 in the yield statement. It will also receive true/false status of coroutine execution.
  • Another thing about coroutines is how the next params of resume call is taken care of, in the above example; you can observe that the variable coroutine.yield will receive the next call params which provides a strong way of doing new operation with the retentionship of existing param values.
  • Finally, after all the statements in the coroutines are executed, subsequent calls will return in false and "cannot resume dead coroutine" statement as response.

Another Coroutine Example

Let’s look at a simple coroutine which returns a number from 1 to 5 with the help of yield function and resume function. It will create coroutine if not available or else resumes the existing coroutine.

When you run the above program, below output will be displayed.

coroutines are often compared with the threads of multiprogramming languages, but you should understand that coroutines will have similar features of thread however they execute only one at a time and they never execute concurrently.

We can control the program execution sequence to meet the requirements with the provision of retaining certain information temporarily. Using global variables with coroutines will provide more flexibility to coroutines.

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd Protection Status

Lua (programming language) Topics