e44a7e37b6
git-svn-id: https://semanticscuttle.svn.sourceforge.net/svnroot/semanticscuttle/trunk@151 b3834d28-1941-0410-a4f8-b48e95affb8f
408 lines
12 KiB
JavaScript
408 lines
12 KiB
JavaScript
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);
|
|
}
|
|
}
|
|
});
|
|
|
|
}
|