| 1 |
// Copyright 2005 Bob Ippolito. All Rights Reserved. |
| 2 |
// Modifications Copyright 2009 The Closure Library Authors. |
| 3 |
// All Rights Reserved. |
| 4 |
|
| 5 |
/** |
| 6 |
* Portions of this code are from MochiKit, received by The Closure |
| 7 |
* Library Authors under the MIT license. All other code is Copyright |
| 8 |
* 2005-2009 The Closure Library Authors. All Rights Reserved. |
| 9 |
*/ |
| 10 |
|
| 11 |
/** |
| 12 |
* @fileoverview Class for tracking multiple asynchronous operations and |
| 13 |
* handling the results. The DeferredList object here is patterned after the |
| 14 |
* DeferredList object in the Twisted python networking framework. |
| 15 |
* |
| 16 |
* Based on the MochiKit code. |
| 17 |
* |
| 18 |
* See: http://twistedmatrix.com/projects/core/documentation/howto/defer.html |
| 19 |
* |
| 20 |
* @author [email protected] (Shawn Brenneman) |
| 21 |
*/ |
| 22 |
|
| 23 |
goog.provide('goog.async.DeferredList'); |
| 24 |
|
| 25 |
goog.require('goog.async.Deferred'); |
| 26 |
|
| 27 |
|
| 28 |
|
| 29 |
/** |
| 30 |
* Constructs an object that waits on the results of multiple asynchronous |
| 31 |
* operations and marshals the results. It is itself a <code>Deferred</code>, |
| 32 |
* and may have an execution sequence of callback functions added to it. Each |
| 33 |
* <code>DeferredList</code> instance is single use and may be fired only once. |
| 34 |
* |
| 35 |
* The default behavior of a <code>DeferredList</code> is to wait for a success |
| 36 |
* or error result from every <code>Deferred</code> in its input list. Once |
| 37 |
* every result is available, the <code>DeferredList</code>'s execution sequence |
| 38 |
* is fired with a list of <code>[success, result]</code> array pairs, where |
| 39 |
* <code>success</code> is a boolean indicating whether <code>result</code> was |
| 40 |
* the product of a callback or errback. The list's completion criteria and |
| 41 |
* result list may be modified by setting one or more of the boolean options |
| 42 |
* documented below. |
| 43 |
* |
| 44 |
* <code>Deferred</code> instances passed into a <code>DeferredList</code> are |
| 45 |
* independent, and may have additional callbacks and errbacks added to their |
| 46 |
* execution sequences after they are passed as inputs to the list. |
| 47 |
* |
| 48 |
* @param {!Array<!goog.async.Deferred>} list An array of deferred results to |
| 49 |
* wait for. |
| 50 |
* @param {boolean=} opt_fireOnOneCallback Whether to stop waiting as soon as |
| 51 |
* one input completes successfully. In this case, the |
| 52 |
* <code>DeferredList</code>'s callback chain will be called with a two |
| 53 |
* element array, <code>[index, result]</code>, where <code>index</code> |
| 54 |
* identifies which input <code>Deferred</code> produced the successful |
| 55 |
* <code>result</code>. |
| 56 |
* @param {boolean=} opt_fireOnOneErrback Whether to stop waiting as soon as one |
| 57 |
* input reports an error. The failing result is passed to the |
| 58 |
* <code>DeferredList</code>'s errback sequence. |
| 59 |
* @param {boolean=} opt_consumeErrors When true, any errors fired by a |
| 60 |
* <code>Deferred</code> in the input list will be captured and replaced |
| 61 |
* with a succeeding null result. Any callbacks added to the |
| 62 |
* <code>Deferred</code> after its use in the <code>DeferredList</code> will |
| 63 |
* receive null instead of the error. |
| 64 |
* @param {Function=} opt_canceler A function that will be called if the |
| 65 |
* <code>DeferredList</code> is canceled. @see goog.async.Deferred#cancel |
| 66 |
* @param {Object=} opt_defaultScope The default scope to invoke callbacks or |
| 67 |
* errbacks in. |
| 68 |
* @constructor |
| 69 |
* @extends {goog.async.Deferred} |
| 70 |
*/ |
| 71 |
goog.async.DeferredList = function( |
| 72 |
list, opt_fireOnOneCallback, opt_fireOnOneErrback, opt_consumeErrors, |
| 73 |
opt_canceler, opt_defaultScope) { |
| 74 |
|
| 75 |
goog.async.DeferredList.base(this, 'constructor', |
| 76 |
opt_canceler, opt_defaultScope); |
| 77 |
|
| 78 |
/** |
| 79 |
* The list of Deferred objects to wait for. |
| 80 |
* @const {!Array<!goog.async.Deferred>} |
| 81 |
* @private |
| 82 |
*/ |
| 83 |
this.list_ = list; |
| 84 |
|
| 85 |
/** |
| 86 |
* The stored return values of the Deferred objects. |
| 87 |
* @const {!Array} |
| 88 |
* @private |
| 89 |
*/ |
| 90 |
this.deferredResults_ = []; |
| 91 |
|
| 92 |
/** |
| 93 |
* Whether to fire on the first successful callback instead of waiting for |
| 94 |
* every Deferred to complete. |
| 95 |
* @const {boolean} |
| 96 |
* @private |
| 97 |
*/ |
| 98 |
this.fireOnOneCallback_ = !!opt_fireOnOneCallback; |
| 99 |
|
| 100 |
/** |
| 101 |
* Whether to fire on the first error result received instead of waiting for |
| 102 |
* every Deferred to complete. |
| 103 |
* @const {boolean} |
| 104 |
* @private |
| 105 |
*/ |
| 106 |
this.fireOnOneErrback_ = !!opt_fireOnOneErrback; |
| 107 |
|
| 108 |
/** |
| 109 |
* Whether to stop error propagation on the input Deferred objects. If the |
| 110 |
* DeferredList sees an error from one of the Deferred inputs, the error will |
| 111 |
* be captured, and the Deferred will be returned to success state with a null |
| 112 |
* return value. |
| 113 |
* @const {boolean} |
| 114 |
* @private |
| 115 |
*/ |
| 116 |
this.consumeErrors_ = !!opt_consumeErrors; |
| 117 |
|
| 118 |
/** |
| 119 |
* The number of input deferred objects that have fired. |
| 120 |
* @private {number} |
| 121 |
*/ |
| 122 |
this.numFinished_ = 0; |
| 123 |
|
| 124 |
for (var i = 0; i < list.length; i++) { |
| 125 |
var d = list[i]; |
| 126 |
d.addCallbacks(goog.bind(this.handleCallback_, this, i, true), |
| 127 |
goog.bind(this.handleCallback_, this, i, false)); |
| 128 |
} |
| 129 |
|
| 130 |
if (list.length == 0 && !this.fireOnOneCallback_) { |
| 131 |
this.callback(this.deferredResults_); |
| 132 |
} |
| 133 |
}; |
| 134 |
goog.inherits(goog.async.DeferredList, goog.async.Deferred); |
| 135 |
|
| 136 |
|
| 137 |
/** |
| 138 |
* Registers the result from an input deferred callback or errback. The result |
| 139 |
* is returned and may be passed to additional handlers in the callback chain. |
| 140 |
* |
| 141 |
* @param {number} index The index of the firing deferred object in the input |
| 142 |
* list. |
| 143 |
* @param {boolean} success Whether the result is from a callback or errback. |
| 144 |
* @param {*} result The result of the callback or errback. |
| 145 |
* @return {*} The result, to be handled by the next handler in the deferred's |
| 146 |
* callback chain (if any). If consumeErrors is set, an error result is |
| 147 |
* replaced with null. |
| 148 |
* @private |
| 149 |
*/ |
| 150 |
goog.async.DeferredList.prototype.handleCallback_ = function( |
| 151 |
index, success, result) { |
| 152 |
|
| 153 |
this.numFinished_++; |
| 154 |
this.deferredResults_[index] = [success, result]; |
| 155 |
|
| 156 |
if (!this.hasFired()) { |
| 157 |
if (this.fireOnOneCallback_ && success) { |
| 158 |
this.callback([index, result]); |
| 159 |
} else if (this.fireOnOneErrback_ && !success) { |
| 160 |
this.errback(result); |
| 161 |
} else if (this.numFinished_ == this.list_.length) { |
| 162 |
this.callback(this.deferredResults_); |
| 163 |
} |
| 164 |
} |
| 165 |
|
| 166 |
if (this.consumeErrors_ && !success) { |
| 167 |
result = null; |
| 168 |
} |
| 169 |
|
| 170 |
return result; |
| 171 |
}; |
| 172 |
|
| 173 |
|
| 174 |
/** @override */ |
| 175 |
goog.async.DeferredList.prototype.errback = function(res) { |
| 176 |
goog.async.DeferredList.base(this, 'errback', res); |
| 177 |
|
| 178 |
// On error, cancel any pending requests. |
| 179 |
for (var i = 0; i < this.list_.length; i++) { |
| 180 |
this.list_[i].cancel(); |
| 181 |
} |
| 182 |
}; |
| 183 |
|
| 184 |
|
| 185 |
/** |
| 186 |
* Creates a <code>DeferredList</code> that gathers results from multiple |
| 187 |
* <code>Deferred</code> inputs. If all inputs succeed, the callback is fired |
| 188 |
* with the list of results as a flat array. If any input fails, the list's |
| 189 |
* errback is fired immediately with the offending error, and all other pending |
| 190 |
* inputs are canceled. |
| 191 |
* |
| 192 |
* @param {!Array<!goog.async.Deferred>} list The list of <code>Deferred</code> |
| 193 |
* inputs to wait for. |
| 194 |
* @return {!goog.async.Deferred} The deferred list of results from the inputs |
| 195 |
* if they all succeed, or the error result of the first input to fail. |
| 196 |
*/ |
| 197 |
goog.async.DeferredList.gatherResults = function(list) { |
| 198 |
return new goog.async.DeferredList(list, false, true). |
| 199 |
addCallback(function(results) { |
| 200 |
var output = []; |
| 201 |
for (var i = 0; i < results.length; i++) { |
| 202 |
output[i] = results[i][1]; |
| 203 |
} |
| 204 |
return output; |
| 205 |
}); |
| 206 |
}; |