dojo/Deferred¶
| since: | V0.9 |
|---|
Contents
dojo.Deferred manages the communication between asynchronous threads (Callbacks). dojo.Deferred encapsulates a sequence of callbacks in response to a value that may not yet be available. All of dojo.xhr* functions make use of this class, as do many others, such as dojo.io.script.
Introduction¶
dojo.Deferred is an object that allows users to assign callback functions for success and error conditions for a task that may not complete immediately. Such tasks are commonly those generated by calls to dojo.xhrGet, and other IO functions that operate asynchronously.
The basic premise is that an asynchronous task (or even a synchronous task) can return an instance of dojo.Deferred. Users can then call ‘then’ to assign functions for the Deferred to invoke when the task it is monitoring actually completes. If the ‘then’ function is called after the deferred has executed, then the deferred will immediately call those functions with the results of the task.
As with all dojo classes, please see the API documentation for more detail on using dojo.Deferred.
Usage¶
Using a dojo.Deferred is simple. When you are presented with one from another function call as the return, you simply invoke ‘then’ and hand it a function to execute when the Deferred is fired. The ‘then’ function can take an optional second argument that is the callback for an error. Now, if you are creating a deferred for some purpose, you simply instantiate one and return it to the caller. When the task you want to associate with the deferred is complete, you invoke the ‘callback’ or ‘errback’ functions to signal the completion. This in turn will invoke any other callback and errback functions that have been associated with the deferred. See below for details:
Pseudocode Example 1: Creating and calling a deferred.¶
// Dojo 1.7+ (AMD)
require(["dojo/_base/Deferred"], function(Deferred){
var deferred = new Deferred();
setTimeout(function(){ deferred.resolve({success: true}); }, 1000);
return deferred;
});
// Dojo < 1.7
var deferred = new dojo.Deferred();
setTimeout(function(){ deferred.resolve({success: true}); }, 1000);
return deferred;
Pseudocode Example 2: Assigning callbacks to fire when a deferred fires.¶
var deferred = someAsyncFunction();
deferred.then(function(value){
// Do something on success.
},
function(error){
// Do something on failure.
});
dojo.when¶
The dojo.when function is a useful tool for interacting with Deferred objects since it can provide normalization between asynchronous Deferreds and normal synchronous values.
As of Dojo 1.7, the when function is exposed as a member of the dojo/_base/Deferred module return (which is also the Deferred constructor). It is aliased to dojo.when for backward-compatibility.
Deferred objects also have a promise property that provides a read-only view of the result of the operation. This provides a safe robust object that can be passed to other functions without worry of the Deferred being mutated or improperly resolved against expectations.
Examples¶
Example 1: Creating a deferred and adding callbacks¶
dojo.require("dijit.form.Button");
function createDeferred(){
// Create a deferred and set it to fire in 1 second.
var deferred = new dojo.Deferred();
setTimeout(function(){ deferred.resolve({called: true});}, 1000);
dojo.byId("response").innerHTML = "Created a deferred.";
// Add a callback that changes the displayed message after it fires.
deferred.then(function(){
dojo.byId("response").innerHTML = "Deferred has fired.";
});
}
<b>Push the button to create a deferred and set up an async callback</B>
<br>
<br>
<button data-dojo-type="dijit.form.Button" id="deferredButton" onClick="createDeferred();">Create deferred!</button>
<br>
<br>
<b>Result</b>
<div id="response"></div>
See Also¶
- dojo.when()
- dojo.xhrGet()
- Article on the new design of Deferreds in 1.5: http://www.sitepen.com/blog/2010/05/03/robust-promises-with-dojo-deferred-1-5/
- Tutorial “Getting Started with Deferreds” at http://dojotoolkit.org/documentation/tutorials/1.6/deferreds/