Beginners Guide to Coroutines: Difference between revisions

From Legacy Roblox Wiki
Jump to navigationJump to search
>Pwnedu46
Fixed grammatical errors, added the "See Also" section, replaced <code lua></code> with {{code and output}} formatting.
Adding ScriptTutorial template
 
(25 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{ScriptTutorial|easy|scripting}}
== What is a coroutine? ==
== 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 careful though, too many threads mean a lot of lag!
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 careful though, too many threads mean a lot of lag!


== How to create a coroutine ==
== 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.
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.


<code lua>
<syntaxhighlight lang="lua">
function core()
local newThread = coroutine.create(function()
     print("hola")
     print("hola")
end
end)
 
</syntaxhighlight>
new_thread=coroutine.create(core)
</code>


Now you've created your first coroutine and started a new thread! Yet nothing has happened, 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.
Now you've created your first coroutine and started a new thread! Yet nothing has happened, 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.


{{code and output|code =  
{{code and output|code =
function core()
local newThread = coroutine.create(function()
     print("hola")
     print("hola")
end
end)


new_thread=coroutine.create(core)
coroutine.resume(newThread)
 
|output=hola}}
coroutine.resume(new_thread)
|output= hola}}


Let's 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
Let's 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


{{code and output|code =  
{{code and output|code =  
function core(a,b,c)
local newThread = coroutine.create(function(a, b, c)
     print(a*b+c)
     print(a*b + c)
end
end)
new_thread=coroutine.create(core)


coroutine.resume(new_thread,3,5,6)
coroutine.resume(newThread, 3, 5, 6)
|output = 21}}
|output = 21}}


== coroutine.wrap ==
== 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.
''coroutine.wrap()'' can be used 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 assign it to like a function. Think of ''coroutine.wrap'' as a function with a coroutine shoved inside it.


{{code and output|code =  
{{code and output|code =  
function core()
local newThread = coroutine.wrap(function()
     print("Hola")
     print("Hola")
end
end)


new_thread=coroutine.wrap(core)
newThread()
 
new_thread()
|output = Hola}}
|output = Hola}}


Line 53: Line 46:


{{code and output|code =  
{{code and output|code =  
function core(a,b,c)
local newThread = coroutine.wrap(function core(a,b,c)
     print(a*b+c)
     print(a*b+c)
end
end)


new_thread=coroutine.wrap(core)
newThread (8,2,1)
 
new_thread(8,2,1)
|output=17}}
|output=17}}


Line 66: Line 57:
You have learned a couple 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.
You have learned a couple 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.


<code lua>
<syntaxhighlight lang="lua">
local h=Instance.new("Hint",workspace);
local h = Instance.new("Hint", workspace);
local m=Instance.new("Message",workspace);
local m = Instance.new("Message", workspace);
 
local changeHint = coroutine.wrap(function()
    for i = 60, 0, -1 do
      wait(0.5)
      h.Text = i
    end
end)
local changeMessage = coroutine.wrap(function()
    for i = 60, 0, -1 do
        wait(1)
        m.Text = i
    end
end)
 
changeHint()
changeMessage()
</syntaxhighlight>
 
As you can now see, the message and the hint both change their text at the same time, but at different speeds.


coroutine.resume(coroutine.create(function()
Also, coroutine.resume will return error information, like [[pcall]]. ''coroutine.resume()'' will return a boolean, saying if it suceeded, and if it didn't, then a string which is the error message.
    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
{{code and output|code =  
     Wait(1)
local success, errorMessage = coroutine.resume(coroutine.create(function()
     m.Text=i
     ppprint("HI")
end))
 
if not success then -- check if there is an error
     print("There was an error:", errorMessage)
end
end
</code>
|output =
 
There was an error: Script:2: attempt to call global 'ppprint' (a nil value)
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 ==
== more, more coroutines ==
Line 91: Line 99:


{{code and output|code =  
{{code and output|code =  
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=coroutine.wrap(function(param)
new_thread("This was in yield :O")
  print(param)
  local resumedWith = coroutine.yield()
  print("Resumed with: " .. resumedWith)
end)  
new_thread("Hola mis amigos!")
new_thread("This was retrieved with yield()")
|output =  
|output =  
Hola mi amigos!
Hola mis amigos!
yield : This was in yield :O
Resumed with: This was retrieved with yield()
}}
}}


Line 146: Line 154:


== See Also ==
== See Also ==
* [http://wiki.roblox.com/index.php/Function_Dump/Coroutine_Manipulation Coroutines]
*[[Function_Dump/Coroutine Manipulation|Coroutine Manipulation]]
* [http://www.lua.org/pil/9.html Programming in Lua: Coroutine Basics]
*[http://www.lua.org/pil/9.html Programming in Lua: Coroutines]
*[http://www.lua.org/manual/5.1/manual.html#2.11 Lua 5.1 Reference Manual: Coroutines]
*[http://www.lua.org/manual/5.1/manual.html#5.2 Lua 5.1 Reference Manual: Coroutine Manipulation]
 
[[Category:Scripting Tutorials]]

Latest revision as of 21:30, 28 April 2023

This is an easy, scripting related tutorial.

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 careful 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.

local newThread = coroutine.create(function()
    print("hola")
end)

Now you've created your first coroutine and started a new thread! Yet nothing has happened, 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.

local newThread = coroutine.create(function()
    print("hola")
end)

coroutine.resume(newThread)
hola

Let's 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

local newThread = coroutine.create(function(a, b, c)
    print(a*b + c)
end)

coroutine.resume(newThread, 3, 5, 6)
21

coroutine.wrap

coroutine.wrap() can be used 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 assign it to like a function. Think of coroutine.wrap as a function with a coroutine shoved inside it.

local newThread = coroutine.wrap(function()
    print("Hola")
end)

newThread()
Hola

If you want to add in parameters, just do it like you would any other function.

local newThread = coroutine.wrap(function core(a,b,c)
    print(a*b+c)
end)

newThread (8,2,1)
17


What are coroutines really useful for?

You have learned a couple 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.

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

local changeHint = coroutine.wrap(function()
    for i = 60, 0, -1 do
       wait(0.5)
       h.Text = i
    end
end)
local changeMessage = coroutine.wrap(function()
    for i = 60, 0, -1 do
        wait(1)
        m.Text = i
    end
end)

changeHint()
changeMessage()

As you can now see, the message and the hint both change their text at the same time, but at different speeds.

Also, coroutine.resume will return error information, like pcall. coroutine.resume() will return a boolean, saying if it suceeded, and if it didn't, then a string which is the error message.

local success, errorMessage = coroutine.resume(coroutine.create(function()
    ppprint("HI")
end))

if not success then -- check if there is an error
    print("There was an error:", errorMessage)
end
There was an error: Script:2: attempt to call global 'ppprint' (a nil value)

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.

new_thread=coroutine.wrap(function(param)
  print(param)
  local resumedWith = coroutine.yield()
  print("Resumed with: " .. resumedWith)
end) 
new_thread("Hola mis amigos!")
new_thread("This was retrieved with yield()")

Hola mis amigos!

Resumed with: This was retrieved with yield()


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))

suspended hola

dead

coroutine.running()

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

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

print(coroutine.running())
A hexadecimal memory location where the coroutine is stored. (i.e. thread: 183E0548)

See Also