These are the functions in the "coroutine" table.
Coroutines are a very powerful way of splitting execution of a function up until some event occurs (for example, a timer fires, or input arrives). The function chooses when to "yield" execution.
The yield / resume sequence allows variables to be passed back and forward between the thread and the caller. For example the thread can yield with an argument which tells the caller why it yielded, and the caller can resume with an argument telling the thread why it was resumed.
Personally I wouldn't use coroutine.wrap, but stick to something like this:
- Create a new thread using coroutine.create. At this stage it is not yet running.
- Commence executing the function in the thread with coroutine.resume, passing any initial arguments required.
- The thread yields execution, if necessary, using coroutine.yield, passing arguments back to be returned by coroutine.resume. These arguments could indicate the reason for yielding.
- The main script resumes the thread when it is ready to do so, calling coroutine.resume again. This time arguments passed to coroutine.resume are returned as results from the coroutine.yield call. These arguments could indicate the reason the thread is resuming (eg. data received, timeout and so on).
- The previous 2 steps are repeated until it is time for the function to return, effectively terminating the thread.
coroutine.create (f)
Creates a thread consisting of the body f.
thread = coroutine.create (f)
coroutine.resume (thread, v1, v2, ...)
Start or resume a thread created by coroutine.create. Any values supplied after the thread are returned as results from the coroutine.yield inside the thread. If this is the first call for this thread, the values are supplied to the function itself.
On success, returns true, followed by arguments to the coroutine.yield inside the function (if called), or the return value of the function itself.
On failure, returns false followed by an error message.
assert (coroutine.resume (thread, 45, 67))
coroutine.running ()
Returns the running coroutine, or no value when called by the main thread.
coroutine.status (thread)
Returns a string indicating the status of the thread. Raises an error if the argument is not a thread.
If it is, the values returned can be:
- running
- normal
- suspended
- dead
A thread is "running" if coroutine.status is called from within the thread itself.
A thread is "normal" if the coroutine is active, but has resumed another coroutine.
It is "suspended" after being created but before it is resumed, and after yielding.
It is "dead" after it has returned from the entire function.
print (coroutine.status (thread)) --> suspended
coroutine.wrap (f)
Creates a thread with body f, and then returns a function that can be used to resume the thread. This is a slightly simpler interface than the coroutine.create / coroutine.resume sequence, however it makes error management harder.
function f (s)
print ("Entering f with value", s)
v = coroutine.yield ()
print ("After yield, v is", v)
return 22
end -- f
resumer = coroutine.wrap (f)
resumer (88) -- start thread
resumer (99) -- resume after yield
-->
Entering f with value 88
After yield, v is 99
coroutine.yield (v1, v2, ...)
Yields execution back to the caller, effectively creating co-operative multi-tasking. Values supplied to yield are returned to coroutine.resume.
The coroutine cannot be running a C function, a metamethod, or an iterator.
function f (s)
print ("Entering f with value", s)
v = coroutine.yield ("goat")
print ("After yield, v is", v)
return 22
end -- f
thread = coroutine.create (f)
ok, result = coroutine.resume (thread, 42) -- start it up
assert (ok, result) -- check ok
print (result) -- see what the yield returned
ok, result = coroutine.resume (thread, 55) -- resume it
assert (ok, result) -- check ok
print (result) -- see what the function returned
-->
Entering f with value 42
goat
After yield, v is 55
22
See Also ...
Topics
Lua base functions
Lua debug functions
Lua io functions
Lua math functions
Lua os functions
Lua package functions
Lua script extensions
Lua string functions
Lua table functions(Help topic: general=lua_coroutines)
Documentation contents page