Lightweight Web Worker API implementation with native threads
Lightweight Web Worker API implementation with native threads
This is based on @xk (jorgechamorro)'s Threads A GoGo for Node.js, but with an API conforming to the Web Worker standard.
This module provides an asynchronous, evented and/or continuation passing style API for moving blocking/longish CPU-bound tasks out of Node's event loop to JavaScript threads that run in parallel in the background and that use all the available CPU cores automatically; all from within a single Node process.
Note: If you would like to require() native modules in a worker, please consider using the process-based tiny-worker instead. It does not use threads, but the WebWorker API is compatible.
This module requires Node.js 0.10.0+ and a working node-gyp toolchain.
There is an illustrated writeup for the original use case of this module:
With npm:
npm install webworker-threadsSample usage (adapted from MDN):
var Worker = require('webworker-threads').Worker;
// var w = new Worker('worker.js'); // Standard API
// You may also pass in a function:
var worker = new Worker(function(){
postMessage("I'm working before postMessage('ali').");
this.onmessage = function(event) {
postMessage('Hi ' + event.data);
self.close();
};
});
worker.onmessage = function(event) {
console.log("Worker said : " + event.data);
};
worker.postMessage('ali');A more involved example in LiveScript syntax, with five threads:
{ Worker } = require \webworker-threads
for til 5 => (new Worker ->
fibo = (n) -> if n > 1 then fibo(n - 1) + fibo(n - 2) else 1
@onmessage = ({ data }) -> postMessage fibo data
)
..onmessage = ({ data }) ->
console.log "[#{ @thread.id }] #data"
@postMessage Math.ceil Math.random! * 30
..postMessage Math.ceil Math.random! * 30
do spin = -> setImmediate spinAfter the initialization phase of a Node program, whose purpose is to setup listeners and callbacks to be executed in response to events, the next phase, the proper execution of the program, is orchestrated by the event loop whose duty is to juggle events, listeners and callbacks quickly and without any hiccups nor interruptions that would ruin its performance.
Both the event loop and said listeners and callbacks run sequentially in a single thread of execution, Node's main thread. If any of them ever blocks, nothing else will happen for the duration of the block: no more events will be handled, no more callbacks nor listeners nor timeouts nor setImmediate()ed functions will have the chance to run and do their job, because they won't be called by the blocked event loop, and the program will turn sluggish at best, or appear to be frozen and dead at worst.
webworker-threads provides an asynchronous API for CPU-bound tasks that's missing in Node.js:
var Worker = require('webworker-threads').Worker;
require('http').createServer(function (req,res) {
var fibo = new Worker(function() {
function fibo (n) {
return n > 1 ? fibo(n - 1) + fibo(n - 2) : 1;
}
this.onmessage = function (event) {
postMessage(fibo(event.data));
}
});
fibo.onmessage = function (event) {
res.end('fib(40) = ' + event.data);
};
fibo.postMessage(40);
}).listen(port);And it won't block the event loop because for each request, the fibo worker will run in parallel in a separate background thread.
var Threads= require('webworker-threads');new Threads.Worker( [ file | function ] ) returns a Worker object.
Threads.create( /* no arguments */ ) returns a thread object.
Threads.createPool( numberOfThreads ) returns a threadPool object.
var worker= new Threads.Worker('worker.js');
var worker= new Threads.Worker(function(){ ... });
var worker= new Threads.Worker();worker.postMessage({ x: 1, y: 2 }) sends a data structure into the worker. The worker can receive it using the onmessage handler.
worker.onmessage = function (event) { console.log(event.data) }; receives data from the worker's postMessage calls.
worker.terminate() terminates the worker thread.
worker.addEventListener('message', callback) is equivalent to setting worker.onmesssage = callback.
Currently unimplemented.
Currently unimplemented.
Returns the underlying thread object; see the next section for details.
Note that this attribute is implementation-specific, and not part of W3C Web Worker API.
var thread= Threads.create();thread.id is a sequential thread serial number.
thread.load( absolutePath [, cb] ) reads the file at absolutePath and thread.eval(fileContents, cb).
thread.eval( program [, cb]) converts program.toString() and eval()s it in the thread's global context, and (if provided) returns the completion value to cb(err, completionValue).
thread.on( eventType, listener ) registers the listener listener(data) for any events of eventType that the thread thread may emit.
thread.once( eventType, listener ) is like thread.on(), but the listener will only be called once.
thread.removeAllListeners( [eventType] ) deletes all listeners for all eventTypes. If eventType is provided, deletes all listeners only for the event type eventType.
thread.emit( eventType, eventData [, eventData ... ] ) emits an event of eventType with eventData inside the thread thread. All its arguments are .toString()ed.
thread.destroy( /* no arguments */ ) destroys the thread.
threadPool= Threads.createPool( numberOfThreads );threadPool.load( absolutePath [, cb] ) runs thread.load( absolutePath [, cb] ) in all the pool's threads.
threadPool.any.eval( program, cb ) is like thread.eval(), but in any of the pool's threads.
threadPool.any.emit( eventType, eventData [, eventData ... ] ) is like thread.emit(), but in any of the pool's threads.
threadPool.all.eval( program, cb ) is like thread.eval(), but in all the pool's threads.
threadPool.all.emit( eventType, eventData [, eventData ... ] ) is like thread.emit(), but in all the pool's threads.
threadPool.on( eventType, listener ) is like thread.on(), but in all of the pool's threads.
threadPool.totalThreads() returns the number of threads in this pool: as supplied in .createPool( number )
threadPool.idleThreads() returns the number of threads in this pool that are currently idle (sleeping)
threadPool.pendingJobs() returns the number of jobs pending.
threadPool.destroy( [ rudely ] ) waits until pendingJobs() is zero and then destroys the pool. If rudely is truthy, then it doesn't wait for pendingJobs === 0.
Inside every Worker instance from webworker-threads, there's a global self object with these properties:
postMessage({ x: 1, y: 2 }) sends a data structure back to the main thread.
onmessage = function (event) { ... } receives data from the main thread's .postMessage calls.
close() stops the current thread.
addEventListener('message', callback) is equivalent to setting self.onmesssage = callback.
dispatchEvent({ type: 'message', data: data }) is the same as self.postMessage(data).
Currently unimplemented.
importScripts('a.js', 'b.js') loads one or more files from the disk and eval() them in the worker's instance scope.
The underlying thread object; see the next section for details.
Note that this attribute is implementation-specific, and not part of W3C Web Worker API.
Inside every thread .create()d by webworker-threads, there's a global thread object with these properties:
thread.id is the serial number of this thread
thread.on( eventType, listener ) is just like thread.on() above.
thread.once( eventType, listener ) is just like thread.once() above.
thread.emit( eventType, eventData [, eventData ... ] ) is just like thread.emit() above.
thread.removeAllListeners( [eventType] ) is just like thread.removeAllListeners() above.
thread.nextTick( function ) is like process.nextTick(), but much faster.
Inside every thread .create()d by webworker-threads, there are some helpers:
Same as console.log on the main process.
Same as console.log, except it prints to stderr.
puts(arg1 [, arg2 ...]) converts .toString()s and prints its arguments to stdout.
See the developer guide if you want to contribute.
A.- Here's a program that makes Node's event loop spin freely and as fast as possible: it simply prints a dot to the console in each turn:
cat examples/quickIntro_loop.js(function spinForever () {
setImmediate(spinForever);
})();B.- Here's another program that adds to the one above a fibonacci(35) call in each turn, a CPU-bound task that takes quite a while to complete and that blocks the event loop making it spin slowly and clumsily. The point is simply to show that you can't put a job like that in the event loop because Node will stop performing properly when its event loop can't spin fast and freely due to a callback/listener/setImmediate()ed function that's blocking.
cat examples/quickIntro_blocking.jsfunction fibo (n) {
return n > 1 ? fibo(n - 1) + fibo(n - 2) : 1;
}
(function fiboLoop () {
process.stdout.write(fibo(35).toString());
setImmediate(fiboLoop);
})();
(function spinForever () {
setImmediate(spinForever);
})();C.- The program below uses webworker-threads to run the fibonacci(35) calls in a background thread, so Node's event loop isn't blocked at all and can spin freely again at full speed:
cat examples/quickIntro_oneThread.jsfunction fibo (n) {
return n > 1 ? fibo(n - 1) + fibo(n - 2) : 1;
}
function cb (err, dataNo open issues yet, or sync has not completed.