Coroutine

Stub

This article is a stub. You can help the Roblox Wiki by expanding it.

The coroutine library allows for the threading of multiple coroutine functions at once. When using coroutines, the user is able to have different loops and functions being performed at once. Coroutines are represented as the thread data type.

Library

The coroutine library provides functions to manipulate coroutines:

coroutine.create(f: function): thread

Creates a new coroutine, with body f.

coroutine.close(co: thread): boolean

Closes and puts the provided coroutine in a dead state.

coroutine.resume(co: thread, ...: Variant): boolean

Starts or resumes the execution of coroutine co.

coroutine.status(co: thread): string

Returns the status of coroutine co as a string.

coroutine.wrap(f: function): function

Creates a new coroutine and returns a function that, when called, resumes the coroutine.

These functions may be called within a coroutine:

coroutine.isyieldable(): boolean

Returns true if the coroutine this function is called within can safely yield.

coroutine.running(): thread

Returns the running coroutine.

coroutine.yield(...: Tuple): Tuple<Variant>

Suspends execution of the coroutine.

Usage

coroutine.create creates a coroutine from a function. A coroutine does not start and can be started by calling coroutine.resume(coroutine). A coroutine can also receive values by providing parameters. coroutine.resume returns the status and the returned value from the coroutine:

co = coroutine.create(function(a)
    print(a)
    return 10
end)
status, n = coroutine.resume(co, "Hello world!") -- Hello world!
print(status, n) -- true 10

If an error occurs while running the coroutine, it will return the status false with the error message:

function body(a)
    return 10 + a
end
print(coroutine.resume(coroutine.create(body))) -- false 2: attempt to perform arithmetic (add) on number and nil
print(coroutine.resume(coroutine.create(body), 10)) -- true 20

Coroutines have the ability to send and receive values more than once through coroutine.yield, giving them more functionality than functions:

co = coroutine.create(function(a)
    local b = coroutine.yield(a + 1)
    local c = coroutine.yield(b + 2)
    return c + 3
end)
status, n = coroutine.resume(co, 10) -- 10 + 1
print(status, n) -- true 11
status, n = coroutine.resume(co, n) -- 11 + 2
print(status, n) -- true 13
status, n = coroutine.resume(co, n) -- 13 + 3
print(status, n) -- true 16
status, n = coroutine.resume(co, n)
print(status, n) -- false cannot resume dead coroutine

Wrapping

The coroutine.wrap function can be used instead of using coroutine.create and coroutine.resume, where the function will create and return a function that can be called to resume the coroutine and return the values from it. Unlike coroutine.resume, an error occurred running the coroutine will be raised on the call of the function:

function body(a)
	local n = a + 5
	n = n + coroutine.yield(n)
	return n
end
co = coroutine.wrap(body)
print(co(5)) -- 10
print(co(6)) -- 16
print(co(7)) -- Error:9: cannot resume dead coroutine

Status

The coroutine.status function is used to inspect a coroutine's status:

suspended

The coroutine is waiting to be resumed (coroutine.resume). A coroutine begins in this state and enters it when its function calls coroutine.yield.

running

The coroutine is running.

normal

The coroutine is awaiting the yield of another coroutine (coroutine.resume).

dead

Either the coroutine's function has returned or has thrown an error. It cannot be resumed further.

External links

• coroutine on the Roblox Creator Documentation
• Beginners Guide to Coroutines on the Roblox Developer Hub
• 9 – Coroutines on the Lua website