Debian Codegraph @

closure-library/third_party/closure/goog/mochikit/async/deferredlist.js

raw
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 };