source: Dev/branches/rest-dojo-ui/client/dojo/_base/Deferred.js @ 263

define(["./kernel", "./lang"], function(dojo, lang){
        // module:
        //              dojo/_base/Deferred
        // summary:
        //              This module defines dojo.Deferred.

        var mutator = function(){};
        var freeze = Object.freeze || function(){};
        // A deferred provides an API for creating and resolving a promise.
        dojo.Deferred = function(/*Function?*/ canceller){
                // summary:
                //              Deferreds provide a generic means for encapsulating an asynchronous
                //              operation and notifying users of the completion and result of the operation.
                // description:
                //              The dojo.Deferred API is based on the concept of promises that provide a
                //              generic interface into the eventual completion of an asynchronous action.
                //              The motivation for promises fundamentally is about creating a
                //              separation of concerns that allows one to achieve the same type of
                //              call patterns and logical data flow in asynchronous code as can be
                //              achieved in synchronous code. Promises allows one
                //              to be able to call a function purely with arguments needed for
                //              execution, without conflating the call with concerns of whether it is
                //              sync or async. One shouldn't need to alter a call's arguments if the
                //              implementation switches from sync to async (or vice versa). By having
                //              async functions return promises, the concerns of making the call are
                //              separated from the concerns of asynchronous interaction (which are
                //              handled by the promise).
                //
                //              The dojo.Deferred is a type of promise that provides methods for fulfilling the
                //              promise with a successful result or an error. The most important method for
                //              working with Dojo's promises is the then() method, which follows the
                //              CommonJS proposed promise API. An example of using a Dojo promise:
                //
                //              |       var resultingPromise = someAsyncOperation.then(function(result){
                //              |               ... handle result ...
                //              |       },
                //              |       function(error){
                //              |               ... handle error ...
                //              |       });
                //
                //              The .then() call returns a new promise that represents the result of the
                //              execution of the callback. The callbacks will never affect the original promises value.
                //
                //              The dojo.Deferred instances also provide the following functions for backwards compatibility:
                //
                //                      * addCallback(handler)
                //                      * addErrback(handler)
                //                      * callback(result)
                //                      * errback(result)
                //
                //              Callbacks are allowed to return promises 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).then(null, 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 synchronous 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).then(null, function(){
                //              |               promptUserToRecover();
                //              |       });
                //
                //              Note that the caller doesn't have to change his code at all to
                //              handle the asynchronous case.

                var result, finished, isError, head, nextListener;
                var promise = (this.promise = {});

                function complete(value){
                        if(finished){
                                throw new Error("This deferred has already been resolved");
                        }
                        result = value;
                        finished = true;
                        notify();
                }
                function notify(){
                        var mutated;
                        while(!mutated && nextListener){
                                var listener = nextListener;
                                nextListener = nextListener.next;
                                if((mutated = (listener.progress == mutator))){ // assignment and check
                                        finished = false;
                                }
                                var func = (isError ? listener.error : listener.resolved);
                                if(func){
                                        try{
                                                var newResult = func(result);
                                                if (newResult && typeof newResult.then === "function"){
                                                        newResult.then(lang.hitch(listener.deferred, "resolve"), lang.hitch(listener.deferred, "reject"), lang.hitch(listener.deferred, "progress"));
                                                        continue;
                                                }
                                                var unchanged = mutated && newResult === undefined;
                                                if(mutated && !unchanged){
                                                        isError = newResult instanceof Error;
                                                }
                                                listener.deferred[unchanged && isError ? "reject" : "resolve"](unchanged ? result : newResult);
                                        }catch(e){
                                                listener.deferred.reject(e);
                                        }
                                }else{
                                        if(isError){
                                                listener.deferred.reject(result);
                                        }else{
                                                listener.deferred.resolve(result);
                                        }
                                }
                        }
                }
                // calling resolve will resolve the promise
                this.resolve = this.callback = function(value){
                        // summary:
                        //              Fulfills the Deferred instance successfully with the provide value
                        this.fired = 0;
                        this.results = [value, null];
                        complete(value);
                };


                // calling error will indicate that the promise failed
                this.reject = this.errback = function(error){
                        // summary:
                        //              Fulfills the Deferred instance as an error with the provided error
                        isError = true;
                        this.fired = 1;
                        complete(error);
                        this.results = [null, error];
                        if(!error || error.log !== false){
                                (dojo.config.deferredOnError || function(x){ console.error(x); })(error);
                        }
                };
                // call progress to provide updates on the progress on the completion of the promise
                this.progress = function(update){
                        // summary:
                        //              Send progress events to all listeners
                        var listener = nextListener;
                        while(listener){
                                var progress = listener.progress;
                                progress && progress(update);
                                listener = listener.next;
                        }
                };
                this.addCallbacks = function(callback, errback){
                        // summary:
                        //              Adds callback and error callback for this deferred instance.
                        // callback: Function?
                        //              The callback attached to this deferred object.
                        // errback: Function?
                        //              The error callback attached to this deferred object.
                        // returns:
                        //              Returns this deferred object.
                        this.then(callback, errback, mutator);
                        return this;    // dojo.Deferred
                };
                // provide the implementation of the promise
                promise.then = this.then = function(/*Function?*/resolvedCallback, /*Function?*/errorCallback, /*Function?*/progressCallback){
                        // summary:
                        //              Adds a fulfilledHandler, errorHandler, and progressHandler to be called for
                        //              completion of a promise. The fulfilledHandler is called when the promise
                        //              is fulfilled. The errorHandler is called when a promise fails. The
                        //              progressHandler is called for progress events. All arguments are optional
                        //              and non-function values are ignored. The progressHandler is not only an
                        //              optional argument, but progress events are purely optional. Promise
                        //              providers are not required to ever create progress events.
                        //
                        //              This function will return a new promise that is fulfilled when the given
                        //              fulfilledHandler or errorHandler callback is finished. This allows promise
                        //              operations to be chained together. The value returned from the callback
                        //              handler is the fulfillment value for the returned promise. If the callback
                        //              throws an error, the returned promise will be moved to failed state.
                        //
                        // returns: 
                        //              Returns a new promise that represents the result of the
                        //              execution of the callback. The callbacks will never affect the original promises value.
                        // example:
                        //              An example of using a CommonJS compliant promise:
                        //              |       asyncComputeTheAnswerToEverything().
                        //              |               then(addTwo).
                        //              |               then(printResult, onError);
                        //              |       >44
                        //
                        var returnDeferred = progressCallback == mutator ? this : new dojo.Deferred(promise.cancel);
                        var listener = {
                                resolved: resolvedCallback,
                                error: errorCallback,
                                progress: progressCallback,
                                deferred: returnDeferred
                        };
                        if(nextListener){
                                head = head.next = listener;
                        }
                        else{
                                nextListener = head = listener;
                        }
                        if(finished){
                                notify();
                        }
                        return returnDeferred.promise; // Promise
                };
                var deferred = this;
                promise.cancel = this.cancel = function (){
                        // summary:
                        //              Cancels the asynchronous operation
                        if(!finished){
                                var error = canceller && canceller(deferred);
                                if(!finished){
                                        if (!(error instanceof Error)){
                                                error = new Error(error);
                                        }
                                        error.log = false;
                                        deferred.reject(error);
                                }
                        }
                };
                freeze(promise);
        };
        lang.extend(dojo.Deferred, {
                addCallback: function (/*Function*/ callback){
                        // summary:
                        //              Adds successful callback for this deferred instance.
                        // returns:
                        //              Returns this deferred object.
                        return this.addCallbacks(lang.hitch.apply(dojo, arguments));    // dojo.Deferred
                },

                addErrback: function (/*Function*/ errback){
                        // summary:
                        //              Adds error callback for this deferred instance.
                        // returns:
                        //              Returns this deferred object.
                        return this.addCallbacks(null, lang.hitch.apply(dojo, arguments));      // dojo.Deferred
                },

                addBoth: function (/*Function*/ callback){
                        // summary:
                        //              Add handler as both successful callback and error callback for this deferred instance.
                        // returns:
                        //              Returns this deferred object.
                        var enclosed = lang.hitch.apply(dojo, arguments);
                        return this.addCallbacks(enclosed, enclosed);   // dojo.Deferred
                },
                fired: -1
        });

        dojo.Deferred.when = dojo.when = function(promiseOrValue, /*Function?*/ callback, /*Function?*/ errback, /*Function?*/ progressHandler){
                // summary:
                //              This provides normalization between normal synchronous values and
                //              asynchronous promises, so you can interact with them in a common way
                // returns:
                //              Returns a new promise that represents the result of the execution of callback 
                //              when parameter "promiseOrValue" is promise.
                //              Returns the execution result of callback when parameter "promiseOrValue" is value.
                // example:
                //              |       function printFirstAndLast(items){
                //              |               dojo.when(findFirst(items), console.log);
                //              |               dojo.when(findLast(items), console.log);
                //              |       }
                //              |       function findFirst(items){
                //              |               return dojo.when(items, function(items){
                //              |                       return items[0];
                //              |               });
                //              |       }
                //              |       function findLast(items){
                //              |               return dojo.when(items, function(items){
                //              |                       return items[items.length - 1];
                //              |               });
                //              |       }
                //              And now all three of his functions can be used sync or async.
                //              |       printFirstAndLast([1,2,3,4]) will work just as well as
                //              |       printFirstAndLast(dojo.xhrGet(...));

                if(promiseOrValue && typeof promiseOrValue.then === "function"){
                        return promiseOrValue.then(callback, errback, progressHandler);
                }
                return callback ? callback(promiseOrValue) : promiseOrValue;    // Promise
        };

        return dojo.Deferred;
});