node package manager
It’s your turn. Help us improve JavaScript. Take the 2017 JavaScript Ecosystem Survey »


Simple child_process.fork balancer.

Main idea is to provide simple api for creating child workers that will process some messages and reply it back to master process.

Main features:

  • Always keeps at least 1 active (running) worker.
  • Spawns new woker in case if current worker is busy (see below).
  • Allows to specify minimum number of workers to reserve enough workers to answer on messages
  • Allows to specify maxumum number of workers. If all workers are busy, messages would be queued.
  • Allows to limit concurrency of workers (by tracking task completeness, see "Usage"):
    • Setting concurrency to 1 make worker to execute only one message at time (so no async at all)
    • Setting concurrency to 10 make worker to accept up to 10 messages without responding back.
    • Setting concurrency to 0 make worker to receive all messages, no matter on how much was responded. In this no new worker would be ever created.


npm install child-balancer


Original send example:

var cp = require('child_process');
var n = cp.fork(__dirname + '/sub.js');
n.on('message', function(m) {
  console.log('PARENT got message:', m);
n.send({ hello: 'world' });

With child_process:

var Balancer = require('child_balancer');
var n = new Balancer(__dirname + '/sub.js');
n.onMessage(function(m) {
  console.log('PARENT got message:', m);
n.send({ hello: 'world' });

It will create balancer that:

  • Allow each worker to access unlimited number of 'tracked' messages (see "Tracking of completeness")
  • Balancer will create up to 10 workers
  • Balancer will keep always 1 worker active

Tracking of completeness

Balancer has an option to limit number of messages sent to each worker.

To achieve that new type of messages was introduced: $complete messages.

To send message, that should be tracked, you need wrap message in $complete property, like: { '$complete': "Some message" }. This will allow Balancer to track how many tracking messages were sent to worker.

Upon completion, worker should respond to balancer message, that will be wrapped also with $complete property.

Meanwhile both sides can send ordinary messages and they wouldn't be tracked.

To configure Balancer to limit number of messages that could be processed by one client, you need to configure it:

    concurrency: 2


To create new balancer you need: new Balancer(path_to_script, [config]) Where config is an object with such properties:

name type default Description
min_limit Number 1 Minimal number of wokerks. After start balancer will launch this ammount of workers
max_limit Number 16 Maximum number of workers. If all workers busy and there is no possibility to run new worker, messages would be queued.
concurrency Number 10 Maximum number of messages that can be processed by one worker
pulseTime Number 500 Period in ms when balancer need to check if new worker should be run or some worker killed
args Array