{"id":"rodrick160/plua","name":"plua","scope":"rodrick160","platform":"roblox","description":"Provides parallel Luau accessibility within module-oriented script frameworks","version":"1.0.2","latest":"1.0.2","versions":["1.0.0","1.0.1","1.0.2"],"license":"MPL-2.0","licenseRating":"caution","licenseCaveats":["File-level copyleft: if you modify this package's own source files, those modified files must be made available under MPL-2.0. Using it unmodified in a closed-source game is fine."],"licenseVerified":false,"dependencies":{},"integrity":"59f8a33e4b4cae0450a9c139659d5077124e211d850b2bb41da3160befd4d8c9","likes":0,"downloads":0,"install":"forest install rodrick160/plua","url":"https://forest.dev/p/roblox/rodrick160/plua","files":"https://api.forest.dev/ai/package/roblox/rodrick160/plua/files","readme":"# Install\r\n## Wally\r\nInstalling with [Wally](https://github.com/UpliftGames/wally) is recommended.\r\n`rodrick160/plua@1.0.1`\r\n\r\n# Description\r\nPLua is a Roblox multithreading library created with the intent to provide a simple, effective, and efficient interface for parallel computation.\r\n\r\n> [!NOTE]\r\n> This module uses the term \"thread\" differently than conventional Lua contexts. A Lua thread is technically a coroutine, not a true thread.\r\n> While coroutines and threads both refer to an independent line of code execution with its own stack, local variables, and instruction pointer,\r\n> 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,\r\n> meanwhile, has the ability to (but is not guaranteed to) run in a separate CPU core, parallel with other threads.\r\n> \"Thread\" in this module will be used in the context of multithreading.\r\n\r\n> [!NOTE]\r\n> \"Dispatching\" a thread means the same thing as \"running\" the thread.\r\n\r\nPLua 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,\r\nwhich 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\r\nthread pools can then be dispatched to execute their code, and optionally (but usually) joined back into serial execution. If the thread returns one\r\nor more values, they can be retrieved by joining them.\r\n\r\nModules 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\r\na 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\r\npool, each thread's module will be required, and the thread index will be assigned to the ThreadIndex field of the module.\r\nExample use case:\r\n\r\n```lua\r\nlocal TerrainGenerator = {}\r\n\r\nfunction TerrainGenerator.Run(width: number)\r\n\tlocal index = TerrainGenerator.ThreadIndex\r\n\tlocal chunk = Vector2.new(\r\n\t\tindex % width,\r\n\t\tmath.floor(index / width)\r\n\t)\r\n\r\n\t-- Generate the chunk at the calculated position.\r\nend\r\n\r\nreturn TerrainGenerator\r\n```\r\n\r\n# Docs\r\n## Thread\r\n\r\n> [!WARNING]\r\n> Thread objects do not automatically clean themselves; call :Destroy() on Thread objects if they are no longer used.\r\n\r\n### `PLua.CreateThread(module: ModuleScript): Thread`\r\nCreates a single thread.\r\n\r\nExample usage:\r\n```lua\r\nlocal terrainGenerator = script.TerrainGenerator\r\nlocal thread = PLua.CreateThread(terrainGenerator)\r\nthread:Run()\r\nthread:Join(true)\r\nthread:Destroy()\r\n```\r\n\r\nParameters:\r\nModuleScript `module`:\r\n\tThe module to be executed in the thread.\r\n\tSee the top of this document for more information on thread modules.\r\n\r\nReturns:\r\n\tA newly created Thread object.\r\n\r\n### `Thread:Run(...: any...): boolean`\r\nDispatches the thread and begins code execution.\r\n\r\nIf the thread is in the new state, the function yields until it leaves the new state.\r\nOtherwise, if the thread is not suspended (i.e. the thread is running), dispatching will fail.\r\n\r\nArguments passed to Run() will be passed to the Run() function of the thread module.\r\n\r\nReturns a boolean indicating if the thread was successfully dispatched.\r\n\r\n### `Thread:Join(yield: boolean?): (boolean, any...)`\r\nAttempts to join the thread back into serial execution.\r\n\r\nAn optional yield flag can be passed. If this flag is enabled, and the thread is not\r\nsuspended, the function will yield until the thread enters the suspended state. If the\r\nthread is suspended upon calling this function, the yield flag does nothing and the\r\nfunction will not yield.\r\n\r\nReturns a tuple beginning with flag indicating if the thread was successfully joined.\r\nIf the yield flag is enabled, this success flag will always be true. This flag will\r\nonly be false if the yield flag is not enabled and the thread is not suspended.\r\n\r\nFollowing the success flag, the tuple contains any values returned from the thread module's\r\nRun() function.\r\n\r\n### `Thread:Destroy(): boolean`\r\nAttempts to destroy the thread and clean up its used memory.\r\n\r\nIf the thread is running, destruction will fail.\r\nIf necessary, use Join(true) to yield until destruction is permitted.\r\n\r\nReturns a flag indicating if destruction was successful.\r\n\r\n### `Thread:Status(): string`\r\nReturns the current status of the thread as a string:\r\n\"new\", \"suspended\", or \"running\".\r\n\r\n## ThreadPool\r\n\r\n> [!WARNING]\r\n> ThreadPool objects do not automatically clean themselves; call :Destroy() on ThreadPool objects if they are no longer used.\r\n\r\n### `PLua.CreateThreadPool(n: number, module: ModuleScript): ThreadPool`\r\nCreates a thread pool with `n` threads.\r\n\r\nExample usage:\r\n```lua\r\nlocal width = 5\r\nlocal length = 10\r\nlocal terrainGenerator = script.TerrainGenerator\r\nlocal threadPool = PLua.CreateThreadPool(width * length, terrainGenerator)\r\nthreadPool:Run(width)\r\nthreadPool:JoinAll(true)\r\nthreadPool:Destroy()\r\n```\r\n\r\nParameters:\r\nnumber `n`: The number of threads to create.\r\nModuleScript `module`:\r\n\tThe module to be executed in the threads.\r\n\tSee the top of this document for more information on thread modules.\r\n\r\nReturns:\r\n\tA newly created ThreadPool object.\r\n\r\n\r\n### `ThreadPool:Run(...: any...): boolean`\r\nAttempts to dispatch all threads in the thread pool.\r\nIf any threads in the pool are running, dispatching fails immediately.\r\n\r\nIf any thread is in the new state, the function yields until it leaves the new state.\r\n\r\nArguments passed to `Run()` will be passed to the `Run()` function of the thread module.\r\n\r\nReturns a boolean indicating if the threads were successfully dispatched.\r\n\r\n### `ThreadPool:Join(yield: boolean?): boolean`\r\nAttempts to join all threads back into serial execution.\r\n\r\nThe `yield` flag follows the same rules as in `Thread:Join()`, except it will `yield` until all\r\nthreads in the pool are joined.\r\n\r\nReturns a flag indicating if the threads were successfully joined.\r\nIf the `yield` flag is enabled, this success flag will always be true. This flag will\r\nonly be false if the `yield` flag is not enabled and at least one thread is not suspended.\r\n\r\n### `ThreadPool:JoinAtLeast(n: number, yield: boolean?): boolean`\r\nFunctions similarly to `JoinAll()`, except the requirement for success changes from all threads\r\nsuccessfully joining, to only `n` threads needing to join.\r\n\r\n### `ThreadPool:GetJoinResult(threadIndex: number): (boolean, ...any)`\r\nReturns any values returned by `Thread:Join()`, including the success flag.\r\n\r\n`threadIndex` is used to select which thread in the pool to retrieve the return value(s) of.\r\n\r\nIf the thread has not yet joined, or failed to join, the success flag will be false.\r\n\r\n### `ThreadPool:Size(): number`\r\nReturns the number of threads contained in the thread pool.\r\n\r\n### `ThreadPool:Destroy(): boolean`\r\nAttempts to destroy the thread pool and clean up its used memory.\r\n\r\nIf any thread contained in the pool is running, destruction will fail.\r\nIf necessary, use JoinAll(true) to yield until destruction is permitted.\r\n\r\nReturns a flag indicating if destruction was successful.\r\n","readmeTruncated":false}