+++ /dev/null
-if(!dojo._hasResource["dojo._base.Deferred"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code.
-dojo._hasResource["dojo._base.Deferred"] = true;
-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;
-};
-
-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;
- err = new Error("Deferred Cancelled");
- 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);
- },
-
- 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));
- },
-
- 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));
- },
-
- 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._fire();
- }
- return this;
- },
-
- _fire: function(){
- // summary:
- // Used internally to exhaust the callback sequence when a result
- // is available.
- 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; }
- try{
- res = f(res);
- 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++;
- }
- }catch(err){
- console.debug(err);
- fired = 1;
- res = err;
- }
- }
- this.fired = fired;
- this.results[fired] = res;
- if((cb)&&(this.paused)){
- // this is for "tail recursion" in case the dependent
- // deferred is already fired
- res.addBoth(cb);
- }
- }
-});
-
-}
projects / eow / blobdiff