From e44a7e37b6c7b5961adaffc62b9042b8d442938e Mon Sep 17 00:00:00 2001 From: mensonge Date: Thu, 13 Nov 2008 09:49:11 +0000 Subject: New feature: basic Ajax suggestion for tags and implementation of Dojo toolkit git-svn-id: https://semanticscuttle.svn.sourceforge.net/svnroot/semanticscuttle/trunk@151 b3834d28-1941-0410-a4f8-b48e95affb8f --- includes/js/dojo/_base/Deferred.js | 408 +++++++++++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 includes/js/dojo/_base/Deferred.js (limited to 'includes/js/dojo/_base/Deferred.js') 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 . + // 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); + } + } +}); + +} -- cgit v1.2.3