node-threadpool
WARNING: This project is mostly experimental and the API is subject to change.
This package implements thread pools using node 10.5's new worker thread API (see: https://nodejs.org/api/worker_threads.html).
Features
- Lightweight: one dependency (
surrial
) for serialization - Simple API: submit a function, await a result (no need to mess with loading from files, strings, etc.)
- Supports transpiled code (ex: you may use Typescript to define your workers)
- Can send most types of data including maps, sets, etc.
- Supports shared data between threads, see the example
Why
Worker threads are usually expensive to create, a thread pool maintains the threads and allows you to submit work on the fly, without having to pay the cost of recreating threads.
With node's new worker_thread
API, threads in the pool can pass messages to each other and read and write to shared memory.
Usage
Full API documentation can be found here: https://psastras.github.io/node-threadpool/api/modules/executors.html.
If you're familiar with Java's thread pool API, this should be very familiar:
; const pool = Executors;const result = pool; console; // prints "hello world"
Requires node 10.5+. You must run node with the --experimental-worker
flag enabled.
NODE_OPTIONS=--experimental-worker ./server.js
or
node --experimental-worker ./server.js
Detailed Usage Instructions
To install:
yarn add node-threadpool
or
npm install node-threadpool
Import node-threadpool
:
;
Executors contains methods to create different thread pools.
Create a thread pool by calling one of these methods:
// creates a thread pool with 4 threadsconst pool = Executors;
Then submit work to the pool with the submit
method. This method takes in a function with no arguments that returns a Promise. The submit
method itself returns a Promise which is resolved when the function has been executed.
// these execute in parallel (as long as the pool size >= 2)const result1 = pool;const result2 = pool; console; // joins and prints "done1"console; // joins and prints "done2"
See the documentation for full API details.
Note: if you're not using async / await, Promise based functions work just as well.
Warning
You may only access data within the runnable function's context. For example, this is an error:
const hello = "hello";await pool;
Instead, use the optional data
object when submitting the function:
const hello = "hello";await pool;
Similarly you must require third party modules from inside the run method:
await pool;
Examples
Basic Usage
;;console.logawait result; // prints "hello world"
Pass Data
;;map.set"key", "value";;;console.logawait result; // prints "value"
Shared Data
Simple shared array buffer
;; // theres no lock, so in order to write safely we'll use one thread for this toy example// see the next example for atomic usage; // set the data in the shared buffer to 42await pool.submitnew Int32Arrayd = 42, buffer; // read the data from the shared buffer; console.logawait result; // prints 42
Atomics
const buffer = 1 * Int32ArrayBYTES_PER_ELEMENT;const array = buffer;const pool = Executors; const result = pool; Atomics; // change the value from 0, unblocking the worker thread console; // prints 1
TODOs
- Figure out better function / data serialization.
- Support cached thread executor
- Clean up code
- Settle on an API (when node's api is stable)
- Support nested shared buffer serialization
License
MIT Licensed, see the LICENSE file.