Beginners Guide to Coroutines

What is a coroutine?

Coroutines are some of the most interesting, useful parts of lua yet still some of the most misunderstood. When you make a new coroutine, it will create a new thread which is sort of like adding a new script to your place. Be carefull though, too many threads mean a lot of lag!

How to create a coroutine

Creating a coroutine is fairly simple, all you need to start is a function and coroutine.create(). The one parameter of coroutine.create will be the function you wish to run, so like this.

function core()
    print("hola")
end

new_thread=coroutine.create(core)

Now you've created your first coroutine and started a new thread! Yet nothings happening, well this is because you haven't run it. To run your coroutine you will need to use coroutine.resume() and the parameter will be the thread you created

function core()
    print("hola")
end

new_thread=coroutine.create(core)

coroutine.resume(new_thread)

Now in your output you should see "hola." Lets say you wanted to call parameters in your coroutine's function, well then what you will need to do that with is coroutine.resume() like so

function core(a,b,c)
    print(a*b+c)
end

new_thread=coroutine.create(core)

coroutine.resume(new_thread,3,5,6)

Now you should see "21" in the output because 3*5+6 is 21.

coroutine.wrap

coroutine.wrap() can be used in a way, as a replacement for coroutine.resume and coroutine.create. You use coroutine.wrap on the function like coroutine.create but you will use the variable you asign it to like a function. Think of coroutine.wrap as a function with a coroutine shoved inside it.

function core()
    print("Hola")
end

new_thread=coroutine.wrap(core)

new_thread()

This will print "Hola" into the output. If you want to add in parameters, just do it like you would any other function.

function core(a,b,c)
    print(a*b+c
end

new_thread=coroutine.wrap(core)

new_thread(8,2,1)

This will print "17" into the output because 8*2+1 is 17.

What are coroutines really useful for?

You have learned acouple of the coroutine functions, but what can you use them for? Well one of the most useful things, is making loops and functions run at the same time. For example :

local h=Instance.new("Hint",workspace);
local m=Instance.new("Message",workspace);

coroutine.resume(coroutine.create(function()
    for i=60,0,-1 do
       Wait(0.5)
       h.Text=i
end end -- one for the for, one for the function
)--closes create
)--closes resume

for i=60,0,-1 do
Wait(1)
m.Text=i
end

and as you can now see, the message and the hint both change their text at the same time but at different speeds however, they could be the same speed yet for example purposes, they weren't.

more, more coroutines

coroutine.yield

coroutine.yield puts your coroutine in suspended mode, where it just stops and waits until the coroutine is called again. coroutine.yield cannot include a metamethod, C function or an iterator. ( if you don't know what those are then you're most likely not using them. ) Anything extra put inside a coroutine.yield will go straight to coroutine.resume.

function core(param)
  print (param)
  stuff_will_be_here=coroutine.yield()
  print ("yield : " .. stuff_will_be_here)
end

new_thread=coroutine.wrap(core) 
new_thread("Hola mi amigos!")
new_thread("This was in yield :O")

This will print
Hola mi amigos!
yield : This was in yield :O

coroutine.status

coroutine.status will tell you if your coroutine is either dead, suspended,running or normal. It will return this as a string to you. What do those mean?

• running means that the coroutine is currently working and using its code.
• dead means that the coroutine has stopped running and is done for now.
• suspended means coroutine.yield() ran and it's waiting to start up again.
• normal means it hasn't been told to start running yet.

Now how do we use it? We simply do

function core()
    print("hola")
end

new_thread=coroutine.create(core)

print(coroutine.status(new_thread))

coroutine.resume(new_thread)

print(coroutine.status(new_thread))

This will print
suspended
hola
dead
in the output.

coroutine.running()

coroutine.running() will return the current thread that is running. Example

new_thread=coroutine.create(function()
   print("hola")
end)

print(coroutine.running())

This will put something like : thread: 183E0548 in the output.