Parallel luau

by:

haotian2006

Parallel Luau is a way of achieving real multithreading in roblox using the Actor instance.

Actors

Actors is an Instance that allows scripts under that Actor to run in Parallel.

--Script1
local module = require(...)
module.X = 1
print(module.X) --> 1

--Script2
local module = require(...)
task.wait(1)
print(module.X) --> 1

--Script Under Actor
local module = require(...)
task.wait(1)
print(module.X) --> nil

Communicating Between Threads

There are currently 4 ways to efficiently communicate between threads: Actor Messaging API, Shared Tables, Bindables, or Direct Data Model Communication.

Actor Messaging API

The Actor Messaging API allows a script to receive data from other actors or the main thread. It currently consists of 3 methods: SendMessage(), BindToMessage(), and BindToMessageParallel().

SendMessage

Used to Send Messages between threads. The first argument would be the key while the rest will be the data to send

local Actor = ...
workerActor:SendMessage("myKey", "hello world")

BindToMessage(Parallel)

Used to receive data. If BindToMessageParallel was used then run the code in Parallel. The first Parameter is the key while the second Parameter is a callback.

local Actor = script:GetActor()
Actor:BindToMessage("myKey", function(data)
    print(data)
end)

Actor:BindToMessageParallel("myKey", function(data)
    print(data)
end)

Shared Tables

Shared Table is like a normal table except its contents are shared between threads. This means that if you update a value in one thread, it will also update for other threads.

local SharedTableRegistry = game:GetService("SharedTableRegistry")
local SharedTable = SharedTableRegistry:GetSharedTable("mySharedTable")
--//Parallel Thread
SharedTable.X = 1
--//Another Parallel Thread
print(SharedTable.X) --> 1

Bindables

One of the best ways currently (In my Opinion) to send data between threads is using Bindables as they are almost 4x more efficient than SharedTables.

--//main Thread
local Actor = ...
local BindableFunction = Actor.Bindable
-- assuming you have an event/function parented to the Actor

local data = BindableFunction:Invoke("DoSomething")


--//Actor Script
local Actor = script:GetActor()
local BindableFunction = Actor.Bindable
BindableFunction.OnInvoke(data)
    task.desynchronized() -- runs in parallel
    return doSomething(data)
end

--//before
local data = {
    [1] = "String1",
    [2] = "String1",
    [3] = "String3",
    [4] = "String2",
    [5] = "String2",
}
return data
-----------------------------------------
--//after
local key = {
    [1] = "String1",
    [2] = "String2",
    [3] = "String3",
}
local data = {
    [1] = 1,
    [2] = 1,
    [3] = 3,
    [4] = 2,
    [5] = 2,
}
--to get the value of an index you can do key[valueAtIndex]
return data,key
--or
return {data,key}

Direct Data Model Communication

This type of communication uses the Instances under the game and modifying/reading their properties. However, to maintain thread-safety roblox has systems that disallow threads that are desynchronized to read/write to the Instances.

Thread Safety

Thread Safety is the avoidance of race conditions, Which happens when multiple threads try to read and write to a shared resource causing unwanted behaviors. When using Parallel lua with roblox’s DataModel. Roblox already has Thread Safety implemented into its Instances. Roblox has 4 Safety Levels: Unsafe, Read Parallel, Local Safe, and Safe. You can tell if a function/property has one of these tags by looking at the Roblox’s API. If it has no tags then it defaults to UnSafe.

Race Conditions

Race Conditions are when a thread reads or writes data when another thread is not finished computing that data, causing data to overlap or create unexpected behaviors.

--Example
local SharedTable = ...
SharedTable.Value = 0
--Let's say we are trying to add to a key called Value in the SharedTable
--Each Thread will add 100 to the Value Key

--//Parallel Thread
for i = 1,100 do
    SharedTable.Value = SharedTable.Value + 1
end

--//Another Parallel Thread
for i = 1,100 do
    SharedTable.Value = SharedTable.Value + 1
end

--//Outside of Parallel (After Parallel Threads ran)
print(SharedTable.Value)
--> This won't always print 200 as both Parallel are writing to The Value
--at the same time which can overlap

Avoiding Race Conditions

When working with the DataModel roblox already implemented Thread Safety as shown above. Otherwise what you can do is combine the data in a Synchronized state so there is a lesser chance of data overlapping with each other or if you are working with a shared table use the functions increment() or update() to update data as it does an atomic update to the values.

Using Microprofiler

To open microprofiler on the client press ctrl-shift-f6. To pause press ctrl-P, If it opens an object viewer press ctrl-shift-f6 twice to reopen it and press ctrl-P again.

Using the Debug Library

You can use profilebegin to help find how long your tasks takes.

local function is_prime(n)
    if n <= 1 then
        return false
    end
    for i = 2, math.sqrt(n) do
        if n % i == 0 then
            return false
        end
    end
    return true
end
local function calculatePrimesFrom(from,to)
    debug.profilebegin("primes")
    local primes = {}
    for i = from,to do
        table.insert(primes,is_prime(i))
    end
    debug.profileend()
    return primes
end
calculatePrimesFrom(0,10000)

This will allow you to see how long primes takes to calculate.

which you can see here takes 1.313 ms

Accessing MicroProfiler for Server

To see the microprofiler of a server you would need to go to Developer Console (f9) and go to the MicroProfiler tab.

After that, I recommend setting Frames Per Second to 60 and Seconds to Record to 4 (maximum time). And to Record press Start Recording. After it is done Recording it will display a path in which it is saved. Follow that and you can view the data in a browser.

Why multithread

Multithreading can help increase performance by a lot. For example, if we try to calculate the primes from 0-100000 it will take the server

The tasks takes 26.920ms to calculate which is going to cause performance issues as each frame lasts 1/60 seconds which is ~16ms and since the task takes over 16ms the server will lag for 10ms.

But if we split the tasks into 8 separate tasks

each task only takes about 4ms and since they are running in parallel to each other calculating 100000 primes only takes 4ms in total.

Utilizing Parallel Luau properly

When using Parallel Luau it is recommended to separate tasks into smaller tasks. So let’s say you have a task that takes 5ms to compute on a single thread. What you can do is split the tasks into 5 threads, Each chunk taking ~1 ms to compute, Saving 4 ms. Also when using Parallel Luau avoid yielding threads with wait or coroutine. Because when you use task.wait it will bring it out of parallel. And it is also recommended to Avoid long tasks as it will cause the main Thread (not to be confused with the Main script in the Image) to wait for that parallel task to finish. Show below with the Sleep timer.

What we could have done better here was to split the tasks into smaller tasks and use more Actors.

How many actors should you use

On a roblox server there is only 2 usable worker threads. While on the client it depends on the client’s device but roblox can only have 8 maxmum workers. Workers are just how many threads can be utilized. Every time you run a parallel task the task will go to one of these workers. Roblox will try to balance which Worker should a task go to.

So when determining the number of Actors you want to use it is usually recommended to use more Actors than workers as roblox will balance the tasks between workers.

but avoid using too many or else other problems such as memory will show up.

Conclusion

Parallel Luau is not an easy thing to explain and understand so don’t worry if you don’t understand. If you want to see the code I used for the Images above, make a copy of this place. If you want to learn more about Parallel Luau check out here.