{"id":"studio-delusion/workers","name":"workers","scope":"studio-delusion","platform":"roblox","description":"Mirrored from the Wally registry.","version":"0.1.1","latest":"0.1.1","versions":["0.1.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"4d764bf242f32296d6f00d2209758bb0267a9d606c808e1b6ed47fcccdb16b9a","likes":0,"downloads":0,"install":"forest install studio-delusion/workers","url":"https://forest.dev/p/roblox/studio-delusion/workers","files":"https://api.forest.dev/ai/package/roblox/studio-delusion/workers/files","readme":"# workers\r\n\r\nworkers is a Roblox library for code parallization through the use of Actors.\r\n\r\n# Usage\r\n\r\n> [!NOTE]\r\n> In Luau, threads are coroutines. Coroutines are executed serially by a single CPU core, as opposed to \"real\" threads, which have the ability to run on different CPU cores.\r\n> Therefore, any references to threads are references to \"real\" threads.\r\n\r\n> [!CAUTION]\r\n> Be smart about what you parallelize. More ofter than not it'll lead to worse results than doing it normally.\r\n> If you think something is gonna benefit from splitting it across threads, first benchmark it.\r\n> Read [this article by Roblox](https://create.roblox.com/docs/scripting/multithreading) before parallelizing your code.\r\n\r\n## Workers\r\n\r\nIn order to create a worker, you first need to create a ModuleScript which will house the code you wish to run multithreaded.\r\n```lua\r\n-- hello.luau\r\nlocal Hello = {}\r\n\r\n-- Workers call \"run\" on ModuleScripts\r\nfunction Hello.run()\r\n    print(\"Hello from another thread!\")\r\nend\r\n\r\nreturn Hello\r\n```\r\n\r\nAfterwards, it's as simple as creating a worker with the ModuleScript!\r\n```lua\r\nlocal Workers = require(path.to.workers)\r\nlocal hello = path.to.hello\r\n\r\nlocal worker = Workers.worker(hello)\r\n```\r\n\r\nNow, you can run the ModuleScript on another thread:\r\n```lua\r\nworker:run()\r\n```\r\n\r\nYou can optionally pass values to workers:\r\n```lua\r\n-- hello.luau\r\nlocal Hello = {}\r\n\r\n-- Workers call \"run\" on ModuleScripts\r\nfunction Hello.run(message: string)\r\n    print(`Hello from another thread! My caller says \"{message}\"`)\r\nend\r\n\r\nreturn Hello\r\n```\r\n\r\n```lua\r\nworker:run(\"Hello from caller!\")\r\n```\r\n\r\nYou can return values from `.run()`...\r\n```lua\r\n-- add.luau\r\nlocal Add = {}\r\n\r\n-- Workers call \"run\" on ModuleScripts\r\nfunction Add.run(a: number, b: number): number\r\n    return a + b\r\nend\r\n\r\nreturn Add\r\n```\r\n\r\n...and get them by joining the thread back to serial execution!\r\n```lua\r\nworker:run(2, 2)\r\nlocal ok, result = worker:join()\r\n```\r\n\r\n> [!WARNING]\r\n> `worker:join()` will yield until the worker finishes running.\r\n> You can prevent this by disallowing the worker from attempting to join more than once:\r\n> ```lua\r\n> local ok, result = worker:join(1)\r\n> ```\r\n> or by giving it a certain amount of attempts it can perform before failing:\r\n> ```lua\r\n> local ok, result = worker:join(5)\r\n> ```\r\n\r\n## Pools\r\n\r\nPools work roughly the same as workers, except with a few extra features.\r\n\r\nYou create a ModuleScript\r\n```lua\r\n-- add.luau\r\nlocal Add = {}\r\nAdd.Index = 0 -- The index of the worker in the pool, the worker will automatically set the `Index` behind the curtains, therefore you can make it any number you want in the module\r\n\r\nfunction Add.run(a: number, b: number): number\r\n    return a + b\r\nend\r\n\r\nreturn Add\r\n```\r\n\r\nBind it to a pool\r\n```lua\r\nlocal pool = Workers.pool(10, add) -- Creates a pool bound to the ModuleScript `add` with 10 workers\r\n```\r\n\r\nRun the pool\r\n```lua\r\npool:run(2, 2)\r\n```\r\n\r\nAnd get return values from the pool\r\n```lua\r\nlocal ok = pool:join()\r\nif not ok then return end\r\n\r\nlocal ok, result = pool:get_result(1)\r\n```\r\nYou might have noticed that we joined the pool and called another function with a number.\\\r\nThis is because in the case of pools, `join()` joins all workers back into serial execution **without** returning the results.\\\r\nTherefore we fetch the results with `get_results()` and the index of the worker whose results we want.\r\n\r\nThough, do note that you can simply join the nth worker from the pool you want, and instantly get it's result.\r\n```lua\r\nlocal ok, result = pool:join_nth(1)\r\n```\r\n\r\n## Cleaning up\r\n\r\nYou can clean up workers and pools by calling `:destroy()` on them.\r\n```lua\r\nworker:destroy()\r\npool:destroy()\r\n```\r\n","readmeTruncated":false}