queue-async

Queue

Queue.js is yet another asynchronous helper library for JavaScript. Think of Queue as a minimalist version of Async.js that allows fine-tuning over parallelism. Or, think of it as a version of TameJs that does not use code generation.

For example, if you wanted to stat two files in parallel:

queue()
    .defer(fs.stat, __dirname + "/../Makefile")
    .defer(fs.stat, __dirname + "/../package.json")
    .await(function(error, file1, file2) { console.log(file1, file2); });

Or, if you wanted to run a bazillion asynchronous tasks (here represented as an array of closures) serially:

var q = queue(1);
tasks.forEach(function(t) { q.defer(t); });
q.awaitAll(function(error, results) { console.log("all done!"); });

Queue can be run inside Node.js or in a browser.

Installation

In a browser, you can use the official hosted copy on d3js.org:

<script src="https://d3js.org/queue.v1.min.js"></script>

Queue supports the universal module definition API. For example, with RequireJS:

require.config({
  paths: {
    queue: "https://d3js.org/queue.v1.min"
  }
});

require(["queue"], function(queue) {
  console.log(queue.version);
});

In Node, use NPM to install:

npm install queue-async

And then require("queue-async"). (The package name is queue-async because the name “queue” was already taken.)

API Reference

# queue([parallelism])

Constructs a new queue with the specified parallelism. If parallelism is not specified, the queue has infinite parallelism. Otherwise, parallelism is a positive integer. For example, if parallelism is 1, then all tasks will be run in series. If parallelism is 3, then at most three tasks will be allowed to proceed concurrently; this is useful, for example, when loading resources in a web browser.

# queue.defer(task[, arguments…])

Adds the specified asynchronous task callback to the queue, with any optional arguments. The task will be called with the specified optional arguments and an additional callback argument; the callback must then be invoked by the task when it has finished. The task must invoke the callback with two arguments: the error, if any, and the result of the task. For example:

function simpleTask(callback) {
  setTimeout(function() {
    callback(null, {answer: 42});
  }, 250);
}

To return multiple results from a single callback, wrap those results in an object or array.

If the task calls back with an error, any tasks that were scheduled but not yet started will not run. For a serial queue (of parallelism 1), this means that a task will only run if all previous tasks succeed. For a queue with higher parallelism, only the first error that occurs is reported to the await callback, and tasks that were started before the error occurred will continue to run; note, however, that their results will not be reported to the await callback.

Tasks can only be deferred before queue.await or queue.awaitAll is called. If a task is deferred after then, an error is thrown.

# queue.await(callback)

Sets the callback to be invoked when all deferred tasks have finished. The first argument to the callback is the first error that occurred, or null if no error occurred. If an error occurred, there are no additional arguments to the callback. Otherwise, the callback is passed each result as an additional argument. For example:

queue()
    .defer(fs.stat, __dirname + "/../Makefile")
    .defer(fs.stat, __dirname + "/../package.json")
    .await(function(error, file1, file2) { console.log(file1, file2); });

If all deferred tasks have already completed, the callback will be invoked immediately. This method may only be called once, after any tasks have been deferred. If this method is called multiple times, or if it is called after queue.awaitAll, an error is thrown.

# queue.awaitAll(callback)

Sets the callback to be invoked when all deferred tasks have finished. The first argument to the callback is the first error that occurred, or null if no error occurred. If an error occurred, there are no additional arguments to the callback. Otherwise, the callback is also passed an array of results as the second argument. For example:

queue()
    .defer(fs.stat, __dirname + "/../Makefile")
    .defer(fs.stat, __dirname + "/../package.json")
    .awaitAll(function(error, files) { console.log(files); });

If all deferred tasks have already completed, the callback will be invoked immediately. This method may only be called once, after any tasks have been deferred. If this method is called multiple times, or if it is called after queue.await, an error is thrown.