parallel

Execute functions in parallel and pass the results of all functions to a provided callback.

Usage

var parallel = require( '@stdlib/utils/async/parallel' );

parallel( fcns, [options,] done )

Executes a set of functions in parallel and passes the results of all functions to a provided callback.

function a( clbk ) {
    setTimeout( onTimeout, 0 );
    function onTimeout() {
        clbk( null, 2 );
    }
}

function b( clbk ) {
    setTimeout( onTimeout, 0 );
    function onTimeout() {
        clbk( null, 4 );
    }
}

function done( error, out ) {
    if ( error ) {
        throw error;
    }
    console.log( out );
    // => [ 2, 4 ]
}

var fcns = [ a, b ];

parallel( fcns, done );

The function accepts the following options:

limit: maximum number of functions to execute concurrently. Default: infinity.
thisArg: execution context for each function.

To limit the maximum number of functions executing in parallel, set the limit option.

function a( clbk ) {
    setTimeout( onTimeout, 0 );
    function onTimeout() {
        clbk( null, 2 );
    }
}

function b( clbk ) {
    setTimeout( onTimeout, 0 );
    function onTimeout() {
        clbk( null, 4 );
    }
}

function done( error, out ) {
    if ( error ) {
        throw error;
    }
    console.log( out );
    // => [ 2, 4 ]
}

var fcns = [ a, b ];

var opts = {
    'limit': 1
};

parallel( fcns, opts, done );

To set the this context for all functions in the provided function array, set the thisArg option.

function a( clbk ) {
    this.idx += 1;
    clbk( null, 2 );
}

function b( clbk ) {
    this.idx += 1;
    clbk( null, 4 );
}

var fcns = [ a, b ];
var ctx = {
    'idx': 0
};
var opts = {
    'thisArg': ctx
};

parallel( fcns, opts, done );

function done( error, out ) {
    if ( error ) {
        throw error;
    }
    console.log( ctx.idx );
    // => 2
}

parallel.factory( fcns, [options] )

Returns a reusable function which executes a set of functions in parallel.

function a( clbk ) {
    setTimeout( onTimeout, 0 );
    function onTimeout() {
        clbk( null, 2 );
    }
}

function b( clbk ) {
    setTimeout( onTimeout, 0 );
    function onTimeout() {
        clbk( null, 4 );
    }
}

function done( error, out ) {
    if ( error ) {
        throw error;
    }
    console.log( out );
    // => [ 2, 4 ]
}

var fcns = [ a, b ];

var run = parallel.factory( fcns );

run( done );
run( done );
run( done );

Notes

The order of the results provided to the done callback corresponds to the order of the provided functions.
When executed, each provided function is invoked with a single callback argument. The callback should be invoked upon function completion. The first argument is reserved as an error argument (which can be null). The second argument is reserved for any results which should be passed to the done callback upon completion of all provided functions.
If any function fails to invoke the callback argument, the done callback will never be invoked.
This implementation is intended to start asynchronous tasks so that execution of each task runs concurrently. If provided a function which does not perform asynchronous tasks, the function will execute synchronously. Hence, this implementation does not guarantee that execution is asynchronous. To do so, wrap the done callback in a function which either executes at the end of the current stack (e.g., nextTick) or during a subsequent turn of the event loop (e.g., setImmediate, setTimeout).
The function executes provided functions in the same thread. Accordingly, the function does not spawn new threads.

Examples

var parallel = require( '@stdlib/utils/async/parallel' );

function foo( clbk ) {
    setTimeout( onTimeout, 300 );
    function onTimeout() {
        clbk( null, 'one' );
    }
}

function bar( clbk ) {
    setTimeout( onTimeout, 100 );
    function onTimeout() {
        clbk( null, 'two' );
    }
}

function done( error, results ) {
    if ( error ) {
        throw error;
    }
    console.log( results );
    // => [ 'one', 'two' ]
}

var fcns = [ foo, bar ];

parallel( fcns, done );