root / dojo / trunk / _base / Deferred.js

dojo.provide("dojo._base.Deferred");
dojo.require("dojo._base.lang");

dojo.Deferred = function(/*Function?*/ canceller){
        // summary:
        //              Encapsulates a sequence of callbacks in response to a value that
        //              may not yet be available.  This is modeled after the Deferred class
        //              from Twisted <http://twistedmatrix.com>.
        // description:
        //              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.
        //
        //              The most important methods for Deffered 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 sequence of callbacks is internally represented as a list of
        //              2-tuples containing the callback/errback pair.  For example, the
        //              following call sequence:
        //              
        //              |       var d = new dojo.Deferred();
        //              |       d.addCallback(myCallback);
        //              |       d.addErrback(myErrback);
        //              |       d.addBoth(myBoth);
        //              |       d.addCallbacks(myCallback, myErrback);
        //
        //              is translated into a Deferred with the following internal
        //              representation:
        //
        //              |       [
        //              |               [myCallback, null],
        //              |               [null, myErrback],
        //              |               [myBoth, myBoth],
        //              |               [myCallback, myErrback]
        //              |       ]
        //
        //              The Deferred also keeps track of its current status (fired).  Its
        //              status may be one of three things:
        //
        //                      * -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:
        //
        //                      1. The result given to callback or errback is "instanceof" Error
        //                      2. The previous callback or errback raised an exception while
        //                         executing
        //                      3. The previous callback or errback returned a value
        //                         "instanceof" 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.
        // example:
        //      |       var deferred = new dojo.Deferred();
        //      |       setTimeout(function(){ deferred.callback({success: true}); }, 1000);
        //      |       return deferred;
        // example:
        //              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: no way to add another callback here!!
        // example:
        //              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){
        //              |               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.
        // example:
        //              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
        //              |       function renderLotsOfData(data){
        //              |               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 style
        //              |       renderLotsOfData(someDataObj).addErrback(function(){
        //              |               promptUserToRecover();
        //              |       });
        //
        //              Note that the caller doesn't have to change his code at all to
        //              handle the asynchronous case.

        this.chain = [];
        this.id = this._nextId();
        this.fired = -1;
        this.paused = 0;
        this.results = [null, null];
        this.canceller = canceller;
        this.silentlyCancelled = false;
        this.isFiring = false;
};

dojo.extend(dojo.Deferred, {
        /*
        makeCalled: function(){
                // summary:
                //              returns a new, empty deferred, which is already in the called
                //              state. Calling callback() or errback() on this deferred will
                //              yeild an error and adding new handlers to it will result in
                //              them being called immediately.
                var deferred = new dojo.Deferred();
                deferred.callback();
                return deferred;
        },

        toString: function(){
                var state;
                if(this.fired == -1){
                        state = 'unfired';
                }else{
                        state = this.fired ? 'success' : 'error';
                }
                return 'Deferred(' + this.id + ', ' + state + ')';
        },
        */

        _nextId: (function(){
                var n = 1;
                return function(){ return n++; };
        })(),

        cancel: function(){
                // summary:     
                //              Cancels a Deferred that has not yet received a value, or is
                //              waiting on another Deferred as its value.
                // description:
                //              If a canceller is defined, the canceller is called. If the
                //              canceller did not return an error, or there was no canceller,
                //              then the errback chain is started.
                var err;
                if(this.fired == -1){
                        if(this.canceller){
                                err = this.canceller(this);
                        }else{
                                this.silentlyCancelled = true;
                        }
                        if(this.fired == -1){
                                if(!(err instanceof Error)){
                                        var res = err;
                                        var msg = "Deferred Cancelled";
                                        if(err && err.toString){
                                                msg += ": " + err.toString();
                                        }
                                        err = new Error(msg);
                                        err.dojoType = "cancel";
                                        err.cancelResult = res;
                                }
                                this.errback(err);
                        }
                }else if(       (this.fired == 0) &&
                                        (this.results[0] instanceof dojo.Deferred)
                ){
                        this.results[0].cancel();
                }
        },
                        

        _resback: function(res){
                // summary:
                //              The private primitive that means either callback or errback
                this.fired = ((res instanceof Error) ? 1 : 0);
                this.results[this.fired] = res;
                this._fire();
        },

        _check: function(){
                if(this.fired != -1){
                        if(!this.silentlyCancelled){
                                throw new Error("already called!");
                        }
                        this.silentlyCancelled = false;
                        return;
                }
        },

        callback: function(res){
                //      summary:        
                //              Begin the callback sequence with a non-error value.
                
                /*
                callback or errback should only be called once on a given
                Deferred.
                */
                this._check();
                this._resback(res);
        },

        errback: function(/*Error*/res){
                //      summary: 
                //              Begin the callback sequence with an error result.
                this._check();
                if(!(res instanceof Error)){
                        res = new Error(res);
                }
                this._resback(res);
        },

        addBoth: function(/*Function|Object*/cb, /*String?*/cbfn){
                //      summary:
                //              Add the same function as both a callback and an errback as the
                //              next element on the callback sequence.This is useful for code
                //              that you want to guarantee to run, e.g. a finalizer.
                var enclosed = dojo.hitch.apply(dojo, arguments);
                return this.addCallbacks(enclosed, enclosed); // dojo.Deferred
        },

        addCallback: function(/*Function|Object*/cb, /*String?*/cbfn /*...*/){
                //      summary: 
                //              Add a single callback to the end of the callback sequence.
                return this.addCallbacks(dojo.hitch.apply(dojo, arguments)); // dojo.Deferred
        },

        addErrback: function(cb, cbfn){
                //      summary: 
                //              Add a single callback to the end of the callback sequence.
                return this.addCallbacks(null, dojo.hitch.apply(dojo, arguments)); // dojo.Deferred
        },

        addCallbacks: function(cb, eb){
                // summary: 
                //              Add separate callback and errback to the end of the callback
                //              sequence.
                this.chain.push([cb, eb])
                if(this.fired >= 0 && !this.isFiring){
                        this._fire();
                }
                return this; // dojo.Deferred
        },

        _fire: function(){
                // summary: 
                //              Used internally to exhaust the callback sequence when a result
                //              is available.
                this.isFiring = true;
                var chain = this.chain;
                var fired = this.fired;
                var res = this.results[fired];
                var self = this;
                var cb = null;
                while(
                        (chain.length > 0) &&
                        (this.paused == 0)
                ){
                        // Array
                        var f = chain.shift()[fired];
                        if(!f){ continue; }
                        var func = function(){
                                var ret = f(res);
                                //If no response, then use previous response.
                                if(typeof ret != "undefined"){
                                        res = ret;
                                }
                                fired = ((res instanceof Error) ? 1 : 0);
                                if(res instanceof dojo.Deferred){
                                        cb = function(res){
                                                self._resback(res);
                                                // inlined from _pause()
                                                self.paused--;
                                                if(
                                                        (self.paused == 0) && 
                                                        (self.fired >= 0)
                                                ){
                                                        self._fire();
                                                }
                                        }
                                        // inlined from _unpause
                                        this.paused++;
                                }
                        };
                        if(dojo.config.debugAtAllCosts){
                                func.call(this);
                        }else{
                                try{
                                        func.call(this);
                                }catch(err){
                                        fired = 1;
                                        res = err;
                                }
                        }
                }
                this.fired = fired;
                this.results[fired] = res;
                this.isFiring = false;
                if((cb)&&(this.paused)){
                        // this is for "tail recursion" in case the dependent
                        // deferred is already fired
                        res.addBoth(cb);
                }
        }
});