Forkraft

a node cluster helper lib.

features: clusterize, messaging

Install

    npm install forkraft

clusterize

typical server.js:

var clusterize = require('forkraft').clusterize;

clusterize({
    worker: 'worker.js',
    master: 'master.js'
});

slightly less typical:

var clusterize = require('forkraft').clusterize;

clusterize({
    worker: function() {
        console.log('I am a worker');
    },
    master: function() {
        console.log('I am the master');
    },
    reforkOnDeath: false,
    workersToCoresRatio: 0.5
});

//on a 4 cores system will (eventually) print 'I am a worker' twice and 'I am the master' once

Same as the above only this time called directly:

var clusterize = require('forkraft').clusterize;

clusterize(
    function() {
        console.log('I am a worker');
    },
    function() {
        console.log('I am the master');
    },
    false,
    0.5);

clusterize options reference:

• worker - required, a function to invoke on worker processes or a name of a javascript filename

• master - optional, will be fired after forking code, can be a function or a javascript filename

• reforkOnDeath - optional, whether to refork processes when a worker dies, defaults to true

• workersToCoresRatio - optional, workers to cores ratio expressed in numerical notation (i.e 0.5 = 50% of the cores etc.), default is 1 (100%). In any case there will always be a minimum of one worker. Values over 100% are acceptable and will spawn more workers than cores. The calculation will round the result down (i.e on a system with 5 cores, 0.5 will be rounded down to 2)

• workersCount - optional, en explicit number of worker to start, this will override workersToCoresRatio. A workerstoCoresRation a minumum of 1 worker is enforced.

• workerDeathCallback - optional, a callback to invoke on worker death. specifying this param will override reforkOnDeath behavior.

• env - optional, environment of the worker

---

Messaging

Built on top of a simple type/payload protocol

Simple example

master to worker:

    var Messaging = require('forkraft').Messaging;

    Messaging.on('moo', function(payload) {
        console.log(payload);
    });

    Messaging.send('boom', 'this is the payload', ...reference to worker or worker id...);

worker to master

    var Messaging = require('forkraft').Messaging;

    Messaging.on('boom', function(payload) {
        console.log(payload);
        Messaging.send('moo', 'this is a different payload');
    });

More on receiving:

this:

    function doSomethingWithMyMessage(msg) { // will only get called when message type matches }

    var Messaging = require('forkraft').Messaging;
    Messaging.on('myMessageType', doSomethingWithMyMessage);

replaces this:

    process.on('message', function(message) {
        if (message.type && message.type === 'myMessageType')
            doSomethingWithMyMessage(message);
    });

also works the same in master process, instead of:

    var cluster = require('cluster');

    // spawn cluster and message handler code omitted...

    for (var id in cluster.workers) {
        cluster.workers[id].on('message', messageHandler);
    }

do this:

    function doSomethingWithMyMessage(msg) { // will only get called when message type matches }

    var Messaging = require('forkraft').Messaging;
    Messaging.on('myMessageType', doSomethingWithMyMessage);

Yes, it looks exactly the same as the code used in the worker...

Broadcasting

Messaging.broadcast() on master process

+--------+       +--------+      +--------+
| worker |<------+ master +----->| worker |
+--------+       +---+----+      +--------+
                     |
                     |
                     v
                 +--------+
                 | worker |
                 +--------+

Messaging.broadcast() on worker process

+--------+       +--------+      +--------+
| worker +------>| master +----->| worker |
+--------+       +----+---+      +--------+
                      |
                      |
                      v
 	    		  +--------+
                  | worker |
                  +--------+

at master:

    // code for creating cluster in master omitted ...

    var Messaging = require('forkraft').Messaging;
    Messaging.setupMasterMessageRelay();

    Messaging.broadcast({ type: 'boom' })

at worker1:

    var Messaging = require('forkraft').Messaging;
    Messaging.on('boom'), function(boomMessage) {
        Messaging.broadcast({ type: 'bam' });
    });

at worker2:

var Messaging = require('forkraft').Messaging;
Messaging.on('bam', function() {
    console.log('boom on worker1 set off a bam on worker2');
});

at worker3:

var Messaging = require('forkraft').Messaging;
Messaging.on('bam', function() {
    console.log('boom on worker1 set off a bam on worker3');
});

TODO

• clusterize tests need expansion, they dont test all configuration options
• Messaging needs a live test with real processes (currently has only unit tests with mocks)
• add support for handles exchange