aboutsummaryrefslogtreecommitdiff
path: root/includes/js/dojo/_base/Deferred.js
diff options
context:
space:
mode:
Diffstat (limited to 'includes/js/dojo/_base/Deferred.js')
-rw-r--r--includes/js/dojo/_base/Deferred.js408
1 files changed, 408 insertions, 0 deletions
diff --git a/includes/js/dojo/_base/Deferred.js b/includes/js/dojo/_base/Deferred.js
new file mode 100644
index 0000000..9fe8918
--- /dev/null
+++ b/includes/js/dojo/_base/Deferred.js
@@ -0,0 +1,408 @@
+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);
+ }
+ }
+});
+
+}
generated by cgit v1.2.3 (git 2.39.1) at 2024-07-06 08:46:11 +0000