machinegun
v0.2.0
Published
Async task runner with controlled parallelism (and an angry cat)
Downloads
15
Maintainers
Readme
machinegun
Async task runner with controlled parallelism (and an angry cat)
Installation
npm install machinegun
Basic usage example
Initialisation
// Require the class
var Machinegun = require('machinegun');
// Create an instance
var mg = new Machinegun({
barrels: 1, // Number of parallel tasks, 1 => sequential execution
giveUpOnError: false, // Cancel all the tasks if one fails?
ceaseOnEmpty: false, // Cease fire when magazine is empty?
fireImmediately: true // Trigger the first task immediately after loading?
});
Loading tasks
// A function passed to .load() should either take a callback or return a promise
// It will be triggered by machinegun when it's time to fire this task
mg.load((cb) => {
// The task function should perform some asynchronous operation
var foo = somethingAsynchronous((err) => {
if (err) console.log("I'm errored");
else console.log("I'm succeeded");
// When the operation complete, a callback should be called
cb(err);
// Alternatively the function may return a promise
});
// Hook to machinegun events in order to react to state changes
// while the asynchronous operation is still in progress
mg.on('ceaseFire', foo.pause);
mg.on('fire', foo.resume);
mg.on('giveUp', foo.abort);
});
Flow management
// If the machinegun was set with fireImmediately == false,
// it will need to be started manually
mg.fire()
// Call .ceaseFire() in order to pause the machinegun
someExternalTrigger.on('pause', () => mg.ceaseFire());
// ... and .fire() to start it again
someExternalTrigger.on('resume', () => mg.fire());
// If you want to abort the execution completely, call .giveUp()
someExternalTrigger.on('abort', () => mg.giveUp());
Reference
Initialisation
Module exports a function returning an object. Hence all the below invocation patterns are valid and would produce the same result:
var mg = require('machinegun')(opt);
var Machinegun = require('machinegun');
var mg = new Machinegun(opt);
var machinegun = require('machinegun');
var mg = machinegun(opt);
Machinegun object implements EventEmitter interface. Please refer to the events section below for the full list of emitted events.
Options
barrels
(int)
Number of parallel task execution conveyors. Defaults to 1
which ensures sequential execution. 0
, or any other falsy value would set unlimited parallelism.
giveUpOnError
(bool)
Whether to cancel all running and scheduled tasks in case of an error. Defaults to false
, which means all the tasks will be triggered despite of the errors.
If an error occurs when giveUpOnError
is set to true
, it causes both error
and giveUp
events to be triggered with the error value passed to both as an argument.
ceaseOnEmpty
(bool)
Whether to cease fire after the machinegun has emptied. Defaults to false
, which means a task loaded after the machinegun has emptied will fire immediately. If set to true
the machinegun will have to be implicitly restarted by calling .fire()
after emptied.
fireImmediately
(bool)
Whether to trigger first task execution immediately after it has been loaded. Defaults to true
.
If set to false
the machinegun will be initialised in fireCeased
state and will not start untill .fire()
method is called.
Methods
.load()
Accepts a function, which should either accept a callback parameter or return a promise:
mg.load((cb) => process.nextTick(cb));
mg.load(() => new Promise((resolve, reject) => process.nextTick(resolve)));
If the callback is called with a falsy argument or the promise rejects, an error
event is emitted with an error value or a rejection reason respectively as an argument.
If giveUpOnError
was set to true
the machinegun also gives up, i.e. emits giveUp
event with the same argument and cancels any subsequent tasks.
.fire()
Starts tasks execution in case fireImmediately
was set to false
or if the execution was previously paused with .ceaseFire()
. Causes the machinegun to emit fire
event.
.ceaseFire()
Pauses tasks execution until .fire()
is called.
.giveUp(reason)
Aborts execution. No tasks may be added to the machinegun after it has given up. Nor can it be re-started with .fire()
.
Value of the optional reason
argument will be passed to the giveUp
event handler and, subsequently, to a rejection handler of the promise, returned by .promise()
.
.promise(result)
Returns a promise, which resolves to an optional result
argument value when the machinegun empties and rejects with the above reason
when it gives up.
Events
error
Machinegun will emit error
event if a task has errored. This may be emitted multiple times in case giveUpOnError
was set to false
.
mg.on('error', (err) => console.log("Task errored", err));
Argument passed to the handler will be either a truthy value passed to the callback or a promise rejection reason.
giveUp
Machinegun will emit giveUp
event if a task has errored and giveUpOnError
was set to true
, or when .giveUp()
method was invoked explicitly.
It is not possible to load more tasks after the machinegun has given up.
mg.on('giveUp', (reason) => console.log("White flags up!", reason));
empty
Machinegun will emit empty
after the last task in the magazine has completed.
This will not be emitted if giveUpOnError
was set to true
and there was an error.
However, if giveUpOnError
was set to false
, it will be emitted even if some tasks have errored.
Please note that it is possible to load in more tasks after the magazine has emptied, hence this event may be emitted multiple times.
mg.on('empty', () => console.log("Magazine empty!"));
If ceaseOnEmpty
was set to true
the machinegun will cease fire after emitting this event, also emitting ceaseFire
event. To continue operation .fire()
method has to be called.
fire
and ceaseFire
Machinegun will emit fire
and ceaseFire
events when respective methods are invoked. ceaseFire
will also be emitted after empty
if ceaseOnEmpty
was set to true
.
mg.on('fire', () => console.log("Fire opened"));
mg.on('ceaseFire', () => console.log("Fire ceased"));
Tasks synchronisation
Since one task may error while the other one is still running, as well as to support .ceaseFire()
/.fire()
methods, it is advisable to subscribe to some events within the task function:
mg.load((cb) => {
var foo = somethingAsynchronous((err) => cb(err));
mg.on('ceaseFire', foo.pause);
mg.on('fire', foo.resume);
mg.on('giveUp', foo.abort);
});