define("dojo/_base/Deferred", [ "./kernel", "../Deferred", "../promise/Promise", "../errors/CancelError", "../has", "./lang", "../when" ], function(dojo, NewDeferred, Promise, CancelError, has, lang, when){ // module: // dojo/_base/Deferred var mutator = function(){}; var freeze = Object.freeze || function(){}; // A deferred provides an API for creating and resolving a promise. var Deferred = dojo.Deferred = function(/*Function?*/ canceller){ // summary: // Deprecated. This module defines the legacy dojo/_base/Deferred API. // New code should use dojo/Deferred instead. // description: // The 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 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 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 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 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 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 = new 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(has("config-useDeferredInstrumentation")){ if(isError && NewDeferred.instrumentRejected){ NewDeferred.instrumentRejected(result, !!func); } } 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; if(has("config-useDeferredInstrumentation")){ if(NewDeferred.instrumentRejected){ NewDeferred.instrumentRejected(error, !!nextListener); } } complete(error); this.results = [null, 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; // 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 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 CancelError(error); } error.log = false; deferred.reject(error); } } }; freeze(promise); }; lang.extend(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)); // 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)); // 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); // Deferred }, fired: -1 }); Deferred.when = dojo.when = when; return Deferred; });