@eryx/thread ModuleRun Luau work in isolated child runtimes backed by OS threads.
Threads can be spawned one at a time with thread.spawn, reused through a ThreadPool, or preconfigured as a ThreadWorker for repeated jobs.
Child entrypoints always receive a context object. That context exposes:
value: the initial payload sent by the parentsend(...): publish messages back to the parentupdate(...): publish progress updates for pooled jobsrecv(): wait for a value from the parentExample:
local thread = require("@eryx/thread")
local handle = thread.spawn(function(ctx)
ctx:send("ready")
local input = ctx:recv()
return input * 2
end)
print(handle:recv()) -- "ready"
handle:send(21)
print(handle:join()) -- 42
Context object passed into a child thread entrypoint.
Generic parameters are expressed from the child's point of view:
InitialData: initial payload supplied by the parentSendData: values sent from the child to the parent via sendUpdateData: values published from the child to the parent via updateRecvData: values received from the parent via recvInitial payload provided when the thread or job was started.
Send a message from the child thread back to the parent handle.
Message payload delivered to the parent through handle:recv().
Publish a progress update for a pooled or worker-backed job.
Updates are surfaced on the parent-side future through future.update
and future.onUpdate.
Progress payload to publish to the parent runtime.
Wait for the next message from the parent.
Next payload sent from the parent thread or pooled caller.
Handle to a directly spawned child thread.
Generic parameters are expressed from the parent's point of view:
SendData: values the parent sends to the childRecvData: values the parent receives from the childResultData: final value returned by joinCurrent lifecycle state of the child thread.
Copied exception payload when the thread has failed, otherwise nil.
Optional callback invoked on the parent runtime when the thread errors.
Send a value from the parent to the child thread.
Payload made available to the child through context:recv().
Wait for the next message sent from the child thread.
Next payload published by the child through context:send().
Wait for the thread to finish and return its final result.
Final value returned by the child entrypoint.
Request that the child thread stop as soon as possible.
Handle to a pooled job or worker submission.
wait() returns the job result, while update and onUpdate expose the most
recent progress value published by the child thread.
Current lifecycle state for this queued or running job.
Copied exception payload when the job has failed or been cancelled.
Most recent progress value published by the child, if any.
Optional callback invoked on the parent runtime when the job errors.
Optional callback invoked whenever the child publishes an update.
Wait for the job to finish and return its final result.
Final value returned by the pooled job.
Pool of reusable worker slots for ad-hoc thread jobs.
Maximum number of jobs that may run in parallel.
Number of jobs currently running.
Number of jobs currently queued waiting for a free worker slot.
Default error callback for futures created by this pool.
Default update callback for futures created by this pool.
Queue a job to run on the pool and return a future for its result.
File path or pure Luau function to execute for this job.
Initial payload exposed to the child as context.value.
Future that resolves to the job result and receives progress updates.
Preconfigured worker that reuses the same job entry for every submission.
This is useful when you want pool-like parallelism but do not want to pass the entry function or file path on every call.
Maximum number of jobs that may run in parallel.
Number of jobs currently running.
Number of jobs currently queued waiting for a free worker slot.
Default error callback for futures created by this worker.
Default update callback for futures created by this worker.
Submit one or more payloads to the worker's configured job entry.
When called with one payload, this returns a single future. When called with multiple payloads, it returns an array of futures in the same order as the submitted inputs.
Future when called with one payload, or an array of futures when called with many.
One or more initial payloads to run through the worker's job entry.
Future when called with one payload, or an array of futures when called with many.
Spawn a single child thread immediately.
entry may be a file path or a pure Luau function that can be serialized into
the child runtime. The returned handle can be used for bidirectional messaging,
error observation, and final result collection.
File path or pure Luau function to execute in the child runtime.
Initial payload exposed to the child as context.value.
Handle used to communicate with the child and collect its final result.
Return the number of logical CPUs visible to the host process.
This is a good default upper bound when choosing a pool size for CPU-bound work, though IO-bound workloads may prefer different tuning.
Number of logical CPUs reported by the operating system.
Create a thread pool for running many jobs with bounded concurrency.
Each call to pool:spawn(...) returns a future that resolves when that job
completes.
Pool construction options such as worker-count limits.
Thread pool that queues jobs and runs them with bounded parallelism.
Create a reusable worker with a fixed job entry and bounded concurrency.
Each call to worker:submit(...) reuses the configured job entry and only
changes the submitted payload.
Worker construction options including the shared job entry.
Reusable worker that submits payloads to the configured job entry.
Lifecycle states exposed by a direct thread handle.
Lifecycle states exposed by pooled work items.
Exception payload copied back from a failed child runtime.
Thread entrypoint function.
The generic parameter order is written from the API caller's point of view, but the actual context object flips send/receive directions so the child sees the correct interface:
SendData becomes child RecvDataRecvData becomes child SendDataOptions for constructing a thread pool.
Maximum number of jobs that may run in parallel.
Options for constructing a preconfigured thread worker.
Maximum number of jobs that may run in parallel.
Job entry to run for every submission made through this worker.