Skip to Content | Skip to Navigation


dojo.Deferred

Status:Draft
Version:1.2
Available:since V0.9

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 ‘addCallback’ or ‘addErrback’ to assign functions for the Deferred to invoke when the task it is monitoring actually completes. If either of the addCallback or addErrback functions are 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 ‘addCallback’ and hand it a function to execute when the Deferred is fired. 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.

1
2
3
4
5
<script type="text/javascript">
  var deferred = new dojo.Deferred();
  setTimeout(function(){deferred.callback({success: true}); }, 1000);
  return deferred;
</script>

Pseudocode Example 2: Assigning callbacks to fire when a deferred fires.

1
2
3
4
5
6
7
8
9
<script type="text/javascript">
  var deferred = someAsyncFunction();
  deferred.addCallback(function(value){
    //Do something on success.
  });
  deferred.addErrback(function(value){
    //Do something on failure.
  });
</script>

Examples

Example 1: Creating a deferred and adding callbacks

<script>
  dojo.require("dijit.form.Button");
  function createDeferred() {
    var button = dijit.byId("deferredButton");
    dojo.connect(button, "onClick", function(event){
      //Create a deferred and set it to fire in 1 second.
      var deferred = new dojo.Deferred();
      setTimeout(function(){deferred.callback({called: true})}, 1000);
      dojo.byId("response").innerHTML = "Created a deferred.";
      //Add a callback that changes the displayed message after it fires.
      deferred.addCallback(function(){
        dojo.byId("response").innerHTML = "Deferred has fired.";
      });
    });
  }
  dojo.addOnLoad(createDeferred);
</script>
<b>Push the button to create a deferred and set up an async callback</B>
<br>
<br>
<button dojoType="dijit.form.Button" id="deferredButton">Create deferred!</button>
<br>
<br>
<b>Result</b>
<div id="response"></div>