Coroutine Tutorial

In this tutorial, you can learn all about coroutines, what they do, how to create them, how to run them and precautions you should take when using them. Before you start, though, you might want to be sure you understand functions and other scripting basics.

Use of coroutines

With coroutines you can have two or more things running at once, which is known as multi-threading. You cannot expect two while loops (as shown below) to run simultaneously in the same thread.

while true do 
	wait() 
	print("Hello World!") 
end

while true do 
	wait() 
	print("Goodbye World!") 
end

The code above, as aforementioned, will not run as some people might expect it to. The first loop will hog the running thread unless it is given another one to take up. This is where coroutines come in.

Constructing a coroutine

There is a specific function, create, that is part of the coroutine table which can be used to define a coroutine. For it, a function must be supplied.

Example

function Source()
	while true do
		wait()
		print("Hello World!")
	end
end

local newCoroutine = coroutine.create(Source)

As shown in the above example, there is now a new coroutine by the name of newCoroutine. However, it is simply static and is doing absolutely nothing but allocating virtual memory in its current state. To make the code in the new coroutine run, the resume function will be made of use.

coroutine.resume(newCoroutine)

By adding the above single line to the earlier example code, the following should continuously appear in the output window.

Hello World!

Running code simultaneously

An advantage of using a coroutine is that a thread can quickly be created and integrated into existing code to help run stacks seemingly side-by-side. The following makes use of the complete example above to run two while loops in the same context.

function Source()
	while true do
		wait()
		print("Hello World!")
	end
end

local newCoroutine = coroutine.create(Source)
coroutine.resume(newCoroutine)

while true do
	wait()
	print("Goodbye World!")
end

Hello World! Goodbye World! Hello World! Goodbye World! Hello World! Goodbye World! Hello World!

Goodbye World!

Shortcuts

There are a couple ways to anonymously created new coroutines and run without causing harm to any code originality. Code can either by wrapped with the wrap function or, as mentioned, it can also be anonymously defined.

Example

Anonymously defining:

coroutine.resume(coroutine.create(function() 
	while wait() do 
		print("Hello World") 
	end 
end))

Example

Code wrapping:

coroutine.wrap(function()
	while wait() do 
		print("Hello World") 
	end 
end)()

Information to consider

Whenever a coroutine is ran, then it creates a new thread. This is, in simpler terms, what scripts do other than acquiring a new script context. In essence, many threads will eventually cause lag in a game, so it is best to try and keep the thread count to a minimum by optimizing code and combining all that can be mixed.

Another important fact to remember is that coroutines take on the environment of their parent context of where they were created. So any existing variables of its parent stack, local or global, will fall into the newly created coroutine's envionrment as well. However, from then on, the coroutine will be separate and all of its locals will stay within it.

See Also

• Flowcharts
• Coroutine Manipulation