- The Book of Dojo
- Quick Installation
- Hello World
- Debugging Tutorial
- Introduction
- Part 1: Life With Dojo
- Part 2: Dijit
- Part 3: JavaScript With Dojo and Dijit
- Part 4: Testing, Tuning and Debugging
- Part 5: DojoX
- The Dojo Book, 0.4
Communication Between Threads - dojo.Deferred
Submitted by criecke on Sat, 04/28/2007 - 20:22.
JavaScript has no threads, and even if it did, threads are hard. Deferreds are a way of abstracting non-blocking events, such as the final response to an XMLHttpRequest. Deferreds create a promise to return a response a some point in the future and an easy way to register your interest in receiving that response.
How Does it Work?
Imagine a whiteboard in a math classroom. One professor knows that the maintenance person for this particular classroom is a math genius. So the professor writes on the board a question:
"What is the Shortest Proof for Fermat's Last Theorem? Call x.2591 when you have the answer."
That night, the maintenance worker finds the question on the whiteboard. It's an interesting problem. So he continues to mop the floors thinking about it. (Uhh, does this sound like a movie with Ben Affleck and Matt Damon? Could be...)
Now suppose students would also like the answer. (It'd make a helluva term paper!) They scribble notes underneath like "Also call 555-8244. Also email mathlunkhead@aol.com," etc.
Finally, 8 nights later, the maintenance worker writes down the answer on the whiteboard and calls x.2591, 555-8244, and emails "mathlunkhead@aol.com".
dojo.Deferred is like the whiteboard. At least one person has a question that needs answering by some other entity. In Web 2.0 applications, this is often a server process called by XmlHTTPRequest. Unfortunately, we don't know when the answer will come back. We can either call the process synchronously (we wait by the whiteboard for the answer) or asynchronously (we leave the room and asked to be called).
The email addresses and phone numbers symbolize handlers. A handler is simply a Javascript function called when the answer is complete. These are split between callbacks and errbacks which handle normal completion and errors respectively.
Using Deferreds
The most important methods for Deferred users are:
- addCallback(handler)
- addErrback(handler)
- callback(result)
- errback(result)
In general, when a function returns a Deferred, users then "fill in" the second half of the contract by registering callbacks and error handlers. You may register as many callback and errback handlers as you like and they will be executed in the order registered when a result is provided. Usually this result is provided as the result of an asynchronous operation. The code "managing" the Deferred (the code that made the promise to provide an answer later) will use the callback() and errback() methods to communicate with registered listeners about the result of the operation. At this time, all registered result handlers are called with the most recent result value.
Deferred callback handlers are treated as a chain, and each item in the chain is required to return a value that will be fed into successive handlers. The most minimal callback may be registered like this:
var d = new dojo.Deferred(); d.addCallback(function(result){ return result; });
Perhaps the most common mistake when first using Deferreds is to forget to return a value (in most cases, the value you were passed).
The Deferred also keeps track of its current status, which may be one of three states:
- -1: no value yet (initial condition)
- 0: success
- 1: error
A Deferred will be in the error state if one of the following three conditions are met:
- The result given to callback or errback is an object whose class or superclass is Error, e.g. "instanceof Error" is true.,
- The previous callback or errback raised an exception while executing
- The previous callback or errback returned a value whose class or superclass is "Error"
Otherwise, the Deferred will be in the success state. The state of the Deferred determines the next element in the callback sequence to run.
When a callback or errback occurs with the example deferred chain, something equivalent to the following will happen (imagine that exceptions are caught and returned):
d.callback(result) or d.errback(result) if(!(result instanceof Error)){ result = myCallback(result); } if(result instanceof Error){ result = myErrback(result); } result = myBoth(result); if(result instanceof Error){ result = myErrback(result); }else{ result = myCallback(result); }
The result is then stored away in case another step is added to the callback sequence. Since the Deferred already has a value available, any new callbacks added will be called immediately.
There are two other "advanced" details about this implementation that are useful:
- Callbacks are allowed to return Deferred instances themselves, so you can build complicated sequences of events with ease.
- The creator of the Deferred may specify a canceller. The canceller is a function that will be called if Deferred.cancel is called before the Deferred fires. You can use this to implement clean aborting of an XMLHttpRequest, etc. Note that cancel will fire the deferred with a CancelledError (unless your canceller returns another kind of error), so the errbacks should be prepared to handle that error for cancellable Deferreds.
Deferred objects are often used when making code asynchronous. It may be easiest to write functions in a synchronous manner and then split code using a deferred to trigger a response to a long-lived operation. For example, instead of register a callback function to denote when a rendering operation completes, the function can simply return a deferred:
callback style: |
function renderLotsOfData(data, callback) { var success = false; try{ for(var x in data) { renderDataitem(data[x]); } success = true; }catch(e){ } if(callback){ callback(success); } } |
using callback style: |
renderLotsOfData(someDataObj, function(success){ //handles success or failure if (!success){ promptUserToRecover(); } }); |
NOTE: there's no way to add another callback here!!
Using a Deferred doesn't simplify the sending code any, but it provides a standard interface for callers and senders alike, providing both with a simple way to service multiple callbacks for an operation and freeing both sides from worrying about details such as "did this get called already?". With Deferreds, new callbacks can be added at any time.
Deferred style: |
function renderLotsOfData(data, callback){ var d = new dojo.Deferred(); try { for (var x in data) { renderDataitem(data[x]); } d.callback(true); } catch(e) { d.errback(new Error("rendering failed")); } return d; } |
using Deferred style |
renderLotsOfData(someDataObj).addErrback(function(){ promptUserToRecover(); }); |
NOTE: addErrback and addCallback both return the Deferred again, so we could chain adding callbacks or save the deferred for later should we need to be notified again.
In this example, renderLotsOfData is syncrhonous and so both versions are pretty artificial. Putting the data display on a timeout helps show why Deferreds rock:
Deferred style and async func: |
Deferred stylefunction renderLotsOfData(data, callback){var d = new dojo.Deferred();setTimeout(function(){try{for(var x in data){renderDataitem(data[x]);}d.callback(true);}catch(e){d.errback(new Error("rendering failed"));}}, 100);return d;}using Deferred stylerenderLotsOfData(someDataObj).addErrback(function(){promptUserToRecover();});Note that the caller doesn't have to change his code at all to handle the asynchronous case. |
Author: Alex, with Good Will Hunting analogy provided by Craig Riecke (and Ben and Matt)
- Printer-friendly version
- Login or register to post comments
- Unsubscribe post
Deferred style example function params misleading
The 'callback' parameter in renderLotsOfData in the deferred style example is not needed. Seems to be a copy'n'paste error since it's missing in the documentation in the sourcecode file.
mk