augment

splunkjs.Async.augment

Runs a callback function with additional parameters, which are appended to the parameter list.

Syntax

root.augment = function(callback)

Parameters

Name	Type	Description
callback	Function	The callback function to augment.
rest	Anything...	The number of arguments to add.

Examples

 var callback = function(a, b) {
     console.log(a); //== 1
     console.log(b); //== 2
 };
 var augmented = Async.augment(callback, 2);
 augmented(1);

Source (lib/async.js:531)

root.augment = function(callback) {
        var args = Array.prototype.slice.call(arguments, 1);
        return function() {
            var augmentedArgs = Array.prototype.slice.call(arguments);
            for(var i = 0; i < args.length; i++) {
              augmentedArgs.push(args[i]);
            }
            
            callback.apply(null, augmentedArgs);
        };
    };
})();

chain

splunkjs.Async.chain

Chains asynchronous tasks together by running a function (task) and passing the results as arguments to the next task. When all tasks have been completed or if an error occurs, a callback function is called with the results of the final task.

Each task takes one or more parameters, depending on the previous task in the chain. The last parameter is always the function to run when the task is complete.

err arguments are not passed to individual tasks, but are are propagated to the final callback function.

Syntax

root.chain = function(tasks, callback)

Parameters

Name	Type	Description
tasks	Function	An array of functions: (done).
callback	Function	The function to call when all tasks are done or if an error occurred: (err, ...).

Examples

Async.chain(
    function(callback) { 
        callback(null, 1, 2);
    },
    function(val1, val2, callback) {
        callback(null, val1 + 1);
    },
    function(val1, callback) {
        callback(null, val1 + 1, 5);
    },
    function(err, val1, val2) {
        console.log(val1); //== 3
        console.log(val2); //== 5
    }
);

Source (lib/async.js:449)

root.chain = function(tasks, callback) {
    // Allow for just a list of functions
    if (arguments.length > 1 && utils.isFunction(arguments[0])) {
        var args = utils.toArray(arguments);
        tasks = args.slice(0, args.length - 1);
        callback = args[args.length - 1];
    }
    
    tasks = tasks || [];
    callback = callback || function() {};
    
    if (!tasks.length) {
        callback();
    }
    else {
        var innerChain = function(task, restOfTasks, result) {
            var chainCallback = function(err) {
                if (err) {
                    callback(err);
                    callback = function() {};
                }
                else {
                    var args = utils.toArray(arguments);
                    args.shift();
                    innerChain(restOfTasks[0], restOfTasks.slice(1), args);
                }
            };
            
            var args = result;
            if (!restOfTasks.length) {
                args.push(callback);
            }
            else {
                args.push(chainCallback);
            }
            
            task.apply(null, args);
        };
        
        innerChain(tasks[0], tasks.slice(1), []);
    }
};

parallel

splunkjs.Async.parallel

Runs multiple functions (tasks) in parallel. Each task takes the callback function as a parameter. When all tasks have been completed or if an error occurs, the callback function is called with the combined results of all tasks.

Note: Tasks might not be run in the same order as they appear in the array, but the results will be returned in that order.

Syntax

root.parallel = function(tasks, callback)

Parameters

Name	Type	Description
tasks	Function	An array of functions: (done).
callback	Function	The function to call when all tasks are done or if an error occurred: (err, ...).

Examples

 Async.parallel([
     function(done) {
         done(null, 1);
     },
     function(done) {
         done(null, 2, 3);
     }],
     function(err, one, two) {
         console.log(err); // == null
         console.log(one); // == 1
         console.log(two); // == [1,2]
     }
 );

Source (lib/async.js:102)

root.parallel = function(tasks, callback) {
    // Allow for just a list of functions
    if (arguments.length > 1 && utils.isFunction(arguments[0])) {
        var args = utils.toArray(arguments);
        tasks = args.slice(0, args.length - 1);
        callback = args[args.length - 1];
    }
    
    tasks = tasks || [];
    callback = callback || function() {};
    
    if (tasks.length === 0) {
        callback();
    }
    
    var tasksLeft = tasks.length;
    var results = [];
    var doneCallback = function(idx) {
        return function(err) {
            
            if (err) {
                if (callback) {
                    callback(err);
                }
                callback = null;
            }
            else {
                var args = utils.toArray(arguments);  
                args.shift();
                
                if (args.length === 1) {
                    args = args[0];
                }
                results[idx] = args;
                
                if ((--tasksLeft) === 0) {
                    results.unshift(null);
                    if (callback) {
                        callback.apply(null, results);
                    }
                }
            }
        };
    };
    
    for(var i = 0; i < tasks.length; i++) {
        var task = tasks[i];
        task(doneCallback(i));
    }
};

parallelEach

splunkjs.Async.parallelEach

Applies an asynchronous function over each element in an array, in parallel. A callback function is called when all tasks have been completed. If an error occurs, the callback function is called with an error parameter.

Syntax

root.parallelEach = function(vals, fn, callback)

Parameters

Name	Type	Description
vals	Array	An array of values.
fn	Function	A function (possibly asynchronous) to apply to each element: (done).
callback	Function	The function to call when all tasks are done or if an error occurred: (err).

Examples

 var total = 0;
 Async.parallelEach(
     [1, 2, 3],
     function(val, idx, done) { 
         var go = function() {
             total += val;
             done();
         };
         if (idx === 1) {
             Async.sleep(100, go);    
         }
         else {
             go();
         }
     },
     function(err) {
         console.log(total); // == 6
     }
 );

Source (lib/async.js:369)

root.parallelEach = function(vals, fn, callback) {  
    vals = vals || [];   
    callback = callback || function() {};
    
    root.parallelMap(vals, fn, function(err, result) {
        callback(err); 
    });
};

parallelMap

splunkjs.Async.parallelMap

Runs an asynchronous function (mapping it) over each element in an array, in parallel. When all tasks have been completed or if an error occurs, a callback function is called with the resulting array.

Syntax

root.parallelMap = function(vals, fn, callback)

Parameters

Name	Type	Description
vals	Array	An array of values.
fn	Function	A function (possibly asynchronous) to apply to each element: (done).
callback	Function	The function to call when all tasks are done or if an error occurred: (err, mappedVals).

Examples

 Async.parallelMap(
     [1, 2, 3],
     function(val, idx, done) { 
         if (val === 2) {
             Async.sleep(100, function() { done(null, val+1); });   
         }
         else {
             done(null, val + 1);
         }
     },
     function(err, vals) {
         console.log(vals); // == [2,3,4]
     }
 );

Source (lib/async.js:255)

root.parallelMap = function(vals, fn, callback) {     
    vals = vals || [];
    callback = callback || function() {};
    
    var tasks = [];
    var createTask = function(val, idx) {
        return function(done) { fn(val, idx, done); };
    };
    
    for(var i = 0; i < vals.length; i++) {
        tasks.push(createTask(vals[i], i));
    }
    
    root.parallel(tasks, function(err) {
        if (err) {
            if (callback) {
                callback(err);
            }
            callback = null;
        }
        else {
            var args = utils.toArray(arguments);
            args.shift();
            callback(null, args);
        }
    });
};

series

splunkjs.Async.series

Runs multiple functions (tasks) in series. Each task takes the callback function as a parameter. When all tasks have been completed or if an error occurs, the callback function is called with the combined results of all tasks in the order they were run.

Syntax

root.series = function(tasks, callback)

Parameters

Name	Type	Description
tasks	Function	An array of functions: (done).
callback	Function	The function to call when all tasks are done or if an error occurred: (err, ...).

Examples

 var keeper = 0;
 Async.series([
     function(done) {
         Async.sleep(10, function() {
             console.log(keeper++); // == 0
             done(null, 1);
         });
     },
     function(done) {
         console.log(keeper++); // == 1
         done(null, 2, 3);
     }],
     function(err, one, two) {
         console.log(err); // == null
         console.log(one); // == 1
         console.log(two); // == [1,2]
     }
 );

Source (lib/async.js:186)

root.series = function(tasks, callback) {
    // Allow for just a list of functions
    if (arguments.length > 1 && utils.isFunction(arguments[0])) {
        var args = utils.toArray(arguments);
        tasks = args.slice(0, args.length - 1);
        callback = args[args.length - 1];
    }
    
    tasks = tasks || [];
    callback = callback || function() {};
    
    var innerSeries = function(task, restOfTasks, resultsSoFar, callback) {
        if (!task) {
            resultsSoFar.unshift(null);
            callback.apply(null, resultsSoFar);
            return;
        }
        
        task(function(err) {
            if (err) {
                if (callback) {
                    callback(err);
                }
                callback = null;
            }
            else {
                var args = utils.toArray(arguments);
                args.shift();
                if (args.length === 1) {
                    args = args[0];
                }
                resultsSoFar.push(args);
                
                innerSeries(restOfTasks[0], restOfTasks.slice(1), resultsSoFar, callback);
            }
        });
    };
    
    innerSeries(tasks[0], tasks.slice(1), [], callback);
};

seriesEach

splunkjs.Async.seriesEach

Applies an asynchronous function over each element in an array, in series. A callback function is called when all tasks have been completed. If an error occurs, the callback function is called with an error parameter.

Syntax

root.seriesEach = function(vals, fn, callback)

Parameters

Name	Type	Description
vals	Array	An array of values.
fn	Function	A function (possibly asynchronous)to apply to each element: (done).
callback	Function	The function to call when all tasks are done or if an error occurred: (err).

Examples

 var results = [1, 3, 6];
 var total = 0;
 Async.seriesEach(
     [1, 2, 3],
     function(val, idx, done) { 
         total += val;
         console.log(total === results[idx]); //== true
         done();
     },
     function(err) {
         console.log(total); //== 6
     }
 );

Source (lib/async.js:405)

root.seriesEach = function(vals, fn, callback) {    
    vals = vals || []; 
    callback = callback || function() {};
    
    root.seriesMap(vals, fn, function(err, result) {
        callback(err); 
    });
};

seriesMap

splunkjs.Async.seriesMap

Runs an asynchronous function (mapping it) over each element in an array, in series. When all tasks have been completed or if an error occurs, a callback function is called with the resulting array.

Syntax

root.seriesMap = function(vals, fn, callback)

Parameters

Name	Type	Description
vals	Array	An array of values.
fn	Function	A function (possibly asynchronous) to apply to each element: (done).
callback	Function	The function to call when all tasks are done or if an error occurred: (err, mappedVals).

Examples

 var keeper = 1;
 Async.seriesMap(
     [1, 2, 3],
     function(val, idx, done) { 
         console.log(keeper++); // == 1, then 2, then 3
         done(null, val + 1);
     },
     function(err, vals) {
         console.log(vals); // == [2,3,4];
     }
 );

Source (lib/async.js:308)

root.seriesMap = function(vals, fn, callback) {     
    vals = vals || [];
    callback = callback || function() {};
    
    var tasks = [];
    var createTask = function(val, idx) {
        return function(done) { fn(val, idx, done); };
    };
    
    for(var i = 0; i < vals.length; i++) {
        tasks.push(createTask(vals[i], i));
    }
    
    root.series(tasks, function(err) {
        if (err) {
            if (callback) {
                callback(err);
            }
        }
        else {
            var args = utils.toArray(arguments);
            args.shift();
            callback(null, args);
        }
    });
};

sleep

splunkjs.Async.sleep

Runs a function after a delay (a specified timeout period). The main purpose of this function is to make setTimeout adhere to Node.js-style function signatures.

Syntax

root.sleep = function(timeout, callback)

Parameters

Name	Type	Description
timeout	Number	The timeout period, in milliseconds.
callback	Function	The function to call when the timeout occurs.

Examples

Async.sleep(1000, function() { console.log("TIMEOUT");});

Source (lib/async.js:506)

root.sleep = function(timeout, callback) {
    setTimeout(function() {
        callback();   
    }, timeout);
};

whilst

splunkjs.Async.whilst

Runs an asynchronous while loop.

Syntax

root.whilst = function(condition, body, callback)

Parameters

Name	Type	Description
condition	Function	A function that returns a boolean indicating whether the condition has been met.
body	Function	A function that runs the body of the loop: (done).
callback	Function	The function to call when the loop is complete: (err).

Examples

 var i = 0;
 Async.whilst(
     function() { return i++ < 3; },
     function(done) {
         Async.sleep(0, function() { done(); });
     },
     function(err) {
         console.log(i) // == 3;
     }
 );

Source (lib/async.js:50)

root.whilst = function(condition, body, callback) {  
    condition = condition || function() { return false; };
    body = body || function(done) { done(); };
    callback = callback || function() {};
    
    var iterationDone = function(err) {
        if (err) {
            callback(err);
        }
        else {
            root.whilst(condition, body, callback);
        }
    };
    
    if (condition()) {
        body(iterationDone);
    }
    else {
        callback(null);
    }
};