ThreadBox is a threading library for JavaScript that is built on top of NodeJS worker_threads. It is written to allow for compute intensive JavaScript or WASM processes to be trivially executed in remote worker threads. ThreadBox approaches this by allowing any class decorated with Thread to be spawned and instanced in a remote worker thread. ThreadBox constructs an async interface to the remote worker class, allowing the host thread to invoke operations on the remote worker through simple async method calls.
ThreadBox uses a recursive pattern to spawn worker threads. ThreadBox will recursively call into the applications entry module (typically app.js) and instance a requested Thread class when spawning a new worker. Because each new worker is spawned from the same entry module as the application, class, function and const definitions defined by the application are also available to each subsequent thread. This approach allows for ergonomic same file threading common to other languages.
ThreadBox was built as a research project and is primarily geared towards TypeScript development. It does however provide a non-decorator based fallback API for JavaScript users. This library is offered as is to anyone who may find it of use.
ThreadBox primarily uses decorators to denote Main, Thread and Marshal class types. It also implements [Symbol.asyncIterator] for channels. TypeScript users should configure their environment for the following.
The Main decorator registers a class as the programs entry point. The classes main(...) function will be automatically called by ThreadBox when the program is run.
import { Main } from '@sinclair/threadbox'@Main() class Program { main() { console.log('Hello World') }}// JavaScript users can use __Main(Program) if// decorators are not available.
Thread
The Thread decorator registers a class as threadable which allows it to be spawned in a worker thread. When spawned, the host thread will be able to execute any function available on the class. The class may additionally implement an optional dispose() function that will be invoked when the host thread terminates the worker.
import { Thread } from '@sinclair/threadbox'@Thread() class Worker { add(a: number, b: number) { return a + b } dispose() { console.log('disposed!') }}@Main() default class { async main() { const worker = spawn(Worker) const result = await worker.add(10, 20)
All JavaScript classes can be decorated with @Thread().
Spawn
The spawn(...) function will spawn a threadable class and return a handle to caller allowing it to call methods on the remote class instance. The spawn(...) function may also accept the classes constructor arguments.
The return type of the spawn() function is a ThreadInterface object. This ThreadInterface is a promisfied version of the class interface. The ThreadInterface also provides an additional dispose() function that is available irrespective of if the class has provided an implementation. Calling dispose() on the ThreadInterface will result in the worker being terminated.
Channel
ThreadBox provides a channel API that is built upon the MessageChannel API. ThreadBox channels implement a synchronization protocol that enables a Sender to optionally await for messages to be received by a Receiver. ThreadBox channels are loosely modelled on Rust mpsc channels.
import { channel } from '@sinclair/threadbox'const [sender, receiver] = channel()
The channel Sender and Receiver types can be used to stream sequences of values between cooperating threads. The Sender will async buffer values if the caller does not await on send(). The Receiver type implements [Symbol.asyncIterator] so can be used with for-await-of.
Example 1
The following creates a channel inside the Main thread and sends the Sender to the worker thread. The worker thread will emit values to the Sender which are iterated on within the Main thread.
The following creates a channel inside the worker thread and returns a Receiver on its stream() function. The Main thread then spawns the worker thread and calls stream() and awaits for the Receiver. It then iterates on the Receiver. The into() function is a util function that allows one to move into an async context.
Using channels, its possible to receive on multiple receivers using the select() function. The following demonstrates its use.
import { channel, select } from '@sinclair/threadbox'// setup some channels...const [sender0, receiver0] = channel<number>()const [sender1, receiver1] = channel<string>()const [sender2, receiver2] = channel<boolean>()// send some values...sender0.send(42)sender1.send('hello')sender2.send(true)// receive from any...for await(const value of select([receiver0, receiver1, receiver2])) { // value is number | string | boolean
Marshal
The Marshal decorator registers a class as marshalled. This enables instances of the class to be sent and reconstructed across thread boundaries. ThreadBox will automatically marshal all classes marked with Marshal across Thread function calls, as well as across a channel Sender.
This functionality allows class instances to be transferred to remote threads for remote invocation.
import { spawn, Main, Thread, Marshal } from '@sinclair/threadbox'// Instances of this class can be sent between threads.@Marshal() class Transferrable { method() { console.log('Hello World') }}@Thread() class Worker { execute(instance: Transferrable) { instance.method() // callable }}@Main() default class { async main() { const worker = spawn(Worker)
Note: There is a serialization cost to marshaling. For performance, only Marshal when you need to move logic in and out of threads.
Mutex
ThreadBox provides a Mutex primitive that is built upon JavaScript Atomics. It is used to enter into critical sections of code.
import { Mutex } from '@sinclair/threadbox'const mutex = new Mutex()const lock = mutex.lock()// critical sectionlock.dispose()
The example below spawns 4 instances of the Worker class. A Mutex instance is passed into each worker where by the worker takes a MutexLock on the execute() method. The worker thread holds onto their respective lock for 1 second before releasing. Only 1 of the 4 workers will execute the critical section (below) at one time. The timeout is used to demonstrate the locking behavior.
The following demonstrates using SharedArrayBuffer to parallelize operations performed across a shared Float32Array. The shared buffer is sent to 4 workers with an index to store the result.
import { spawn, Main, Worker } from '@sinclair/threadbox'@Thread() class ComputeForIndex { execute(buffer: Float32Array, index: number) { // sleep 5 seconds const started = Date.now() while((Date.now() - started) < 5000) {} buffer[index] = Math.random() }}@Main() default class { async main() { // 4 x 32bit floats const shared = new