This module brings to you a very lighweight control flow mechanism that it's meant to be the glue between the user calls and the asynchronous nature of your module. It provides a fluent interface, so if your module has an asynchronous API which tends to create the callback pyramid of doom, a deferred queue may help you. It can be also used as a standalone module.
For example, suppose you have an API like the following one:
var r = "file";r;
The above example has two problems: the callback nesting and the error handling. With a deferred queue the example can be rewritten as follows:
var r = "file";r;r;r;r;r;
Look at the reader example for further details.
Projects using this library:
- binary-reader: A real project based on the previous example.
- seraphim: Configuration loading made easy.
async.waterfall() is the function with more similarities with a deferred queue.
//Task 1//Task 2;
Both are very similar but there are 3 big differences:
async's error handling has a major flaw. When something fails you don't know from which task comes the error, so you cannot apply rollback or fallback strategies.
This library separates a task from its result. If you look at the task 1 you can see that push() receives a second function as a parameter, it's the result of the task and is executed between two tasks: the current and the next. If the current task fails, the error is passed to this function and then the
errorevent is emitted (if preventDefault() is not called).
process.nextTick()to call the next task. On the other hand,
deferred-queuedoesn't make any assumption, you decide how to enqueue the tasks; synchronously, asynchronously or both.//Synchronous//Asynchronous//Fake asynchronous (synchronous);
Returns a new DeferredQueue instance.
var dq = ;var q = ;
- DeferredQueue#pause() : undefined
- DeferredQueue#pending() : Number
- DeferredQueue#preventDefault() : undefined
- DeferredQueue#push(task[, result]) : DeferredQueue
- DeferredQueue#resume() : undefined
- DeferredQueue#unshift(task[, result]) : DeferredQueue
Emitted when an error occurs.
Pauses the queue execution. Look at the async-function-between-tasks.js example for further details.
Returns the number of pending tasks in the queue.
Adds a task to the end of the queue and tries to execute it. If there are pending tasks, it simply waits until all the previous tasks have been executed. Think about it like a queue that is permanently executing tasks. Whenever you add a task it can be immediately executed because the queue is empty or enqueued if there are pending tasks that need to be executed first.
task is the function that you want to execute. The
result is a callback that is executed when the task finishes.
The tasks can be synchronous or asynchronous.
You can only return one value. If you want to return an error, throw it, it will be catched. Both the error and the value are passed to the result callback, if any.
If you want to execute an asynchronous task, you must call the
cb parameter when you are ready to continue. As usual, the error is the first parameter.
Note: Being synchronous or asynchronous depends exclusively on the user, but if you use the
cb parameter, a different internal strategy is used. In other words, you can execute a synchronous task using the
cb parameter. This is useful when you need to return more than one value.
There are subtle differences when the tasks are synchronous or asynchronous:
When an error occurs, it is passed to the callback and then, it is emitted. If you don't want to emit the error, call to preventDefault():
I want to execute an asynchronous function inside the result callback
You can. Pause the queue and when you are ready to continue, resume it. Look at the async-function-between-tasks.js example for further details.
Resumes the queue execution. Look at the async-function-between-tasks.js example for further details.
Adds a task to the beginning of the queue. It has the same functionality as the push() function.