Coroutine

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: ): 
:Creates a new coroutine, with body f.
;coroutine.close(co: ): 
:Closes and puts the provided coroutine in a dead state.
;coroutine.resume(co: , ...: ): 
:Starts or resumes the execution of coroutine co.
;coroutine.status(co: ): 
:Returns the status of coroutine co as a string.
;coroutine.wrap(f: ): 
:Creates a new coroutine and returns a function that, when called, resumes the coroutine.
These functions may be called within a coroutine:
;coroutine.isyieldable(): 
:Returns true if the coroutine this function is called within can safely yield.
;coroutine.running(): 
:Returns the running coroutine.
;coroutine.yield(...: ): <>
: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
Category:Scripting