PLua is a Roblox multithreading library created with the intent to provide a simple, effective, and efficient interface for parallel computation.
Note
This module uses the term "thread" differently than conventional Lua contexts. A Lua thread is technically a coroutine, not a true thread. While coroutines and threads both refer to an independent line of code execution with its own stack, local variables, and instruction pointer, they are different in that a coroutine is still executed serially, by a single core of the CPU, as scheduled by the task scheduler. A thread, meanwhile, has the ability to (but is not guaranteed to) run in a separate CPU core, parallel with other threads. "Thread" in this module will be used in the context of multithreading.
Note
"Dispatching" a thread means the same thing as "running" the thread.
PLua allows the user to create, dispatch, and join threads, either on their own or in a thread pool. Threads are provided with a module upon creation, which contains the code to be executed by the thread. In the case of a thread pool, all threads in the pool are given the same module. Threads and thread pools can then be dispatched to execute their code, and optionally (but usually) joined back into serial execution. If the thread returns one or more values, they can be retrieved by joining them.
Modules given to threads are expected to have a Run(...) method. This function will be called when the thread is dispatched. If the thread is part of
a thread pool, it will be assigned a thread index; a number from 1 to n where n is the number of threads in the thread pool. Upon creation of the thread
pool, each thread's module will be required, and the thread index will be assigned to the ThreadIndex field of the module.
Example use case:
local TerrainGenerator = {}
function TerrainGenerator.Run(width: number)
local index = TerrainGenerator.ThreadIndex
local chunk = Vector2.new(
index % width,
math.floor(index / width)
)
-- Generate the chunk at the calculated position.
end
return TerrainGeneratorInstalling with Wally is recommended.
rodrick160/[email protected]
Creates a single thread.
module: ModuleScript- The module to be executed in the thread. See the top of this page for more information on thread modules.
A newly created Thread object.
local terrainGenerator = script.TerrainGenerator
local thread = PLua.CreateThread(terrainGenerator)
thread:Run()
thread:Join(true)
thread:Destroy()Caution
Thread objects do not automatically clean themselves; call Thread:Destroy() on Thread objects if they are no longer used.
Creates a thread pool with n threads.
n: number- The number of threads to create.module: ModuleScript- The module to be executed in the threads. See the top of this page for more information on thread modules.
A newly created ThreadPool object.
local width = 5
local length = 10
local terrainGenerator = script.TerrainGenerator
local threadPool = PLua.CreateThreadPool(width * length, terrainGenerator)
threadPool:Run(width)
threadPool:JoinAll(true)
threadPool:Destroy()Caution
ThreadPool objects do not automatically clean themselves; call ThreadPool:Destroy() on ThreadPool objects if they are no longer used.