dojo.Deferred ¶

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

Contents

dojo.Deferred
- Introduction
- Usage
- Examples
- See Also

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.¶

<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.¶

<script type="text/javascript">
  var deferred = someAsyncFunction();
  deferred.then(function(value){
      //Do something on success.
    },
    function(error){
      //Do something on failure.
  });
</script>

The dojo.when() function is also a useful tool for interacting with Deferred objects since it can provide normalization between asynchronous Deferreds and normal synchronous values.

Deferreds 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¶

<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.then(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>

dojo.Deferred ¶

Introduction ¶

Usage ¶

Pseudocode Example 1: Creating and calling a deferred.¶

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

Examples ¶

Example 1: Creating a deferred and adding callbacks¶

See Also ¶

Table of Contents

dojo.Deferred¶

Introduction¶

Usage¶

Pseudocode Example 1: Creating and calling a deferred.¶

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

Examples¶

Example 1: Creating a deferred and adding callbacks¶

See Also¶

Table of Contents

dojo.Deferred ¶

Introduction ¶

Usage ¶

Examples ¶

See Also ¶