OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.async; | 5 part of dart.async; |
6 | 6 |
7 /** | 7 /** |
8 * A [Future] represents a delayed computation. It is used to obtain a not-yet | 8 * A [Future] represents a delayed computation. It is used to obtain a not-yet |
9 * available value, or error, sometime in the future. Receivers of a | 9 * available value, or error, sometime in the future. Receivers of a |
10 * [Future] can register callbacks that handle the value or error once it is | 10 * [Future] can register callbacks that handle the value or error once it is |
11 * available. For example: | 11 * available. For example: |
12 * | 12 * |
13 * Future<int> future = getFuture(); | 13 * Future<int> future = getFuture(); |
14 * future.then((value) => handleValue(value)) | 14 * future.then((value) => handleValue(value)) |
15 * .catchError((error) => handleError(error)); | 15 * .catchError((error) => handleError(error)); |
16 * | 16 * |
17 * A [Future] can be completed in two ways: with a value ("the future succeeds") | 17 * A [Future] can be completed in two ways: with a value ("the future succeeds") |
18 * or with an error ("the future fails"). Users can install callbacks for each | 18 * or with an error ("the future fails"). Users can install callbacks for each |
19 * case. The result of registering a pair of callbacks is a new Future (the | 19 * case. The result of registering a pair of callbacks is a new Future (the |
20 * "successor") which in turn is completed with the result of invoking the | 20 * "successor") which in turn is completed with the result of invoking the |
21 * corresponding callback. The successor is completed with an error if the | 21 * corresponding callback. The successor is completed with an error if the |
22 * invoked callback throws. For example: | 22 * invoked callback throws. For example: |
23 * | 23 * |
24 * Future<int> successor = future.then((int value) { | 24 * Future<int> successor = future.then((int value) { |
25 * // Invoked when the future is completed with a value. | 25 * // Invoked when the future is completed with a value. |
26 * return 42; // The successor is completed with the value 42. | 26 * return 42; // The successor is completed with the value 42. |
27 * }, | 27 * }, |
28 * onError: (AsyncError e) { | 28 * onError: (e) { |
29 * // Invoked when the future is completed with an error. | 29 * // Invoked when the future is completed with an error. |
30 * if (canHandle(e)) { | 30 * if (canHandle(e)) { |
31 * return 499; // The successor is completed with the value 499. | 31 * return 499; // The successor is completed with the value 499. |
32 * } else { | 32 * } else { |
33 * throw e; // The successor is completed with the error e. | 33 * throw e; // The successor is completed with the error e. |
34 * } | 34 * } |
35 * }); | 35 * }); |
36 * | 36 * |
37 * If a future does not have a successor but is completed with an error, it | 37 * If a future does not have a successor but is completed with an error, it |
38 * forwards the error message to the global error-handler. This special casing | 38 * forwards the error message to the global error-handler. This special casing |
(...skipping 56 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
95 * If calling [function] throws, the created [Future] will be completed | 95 * If calling [function] throws, the created [Future] will be completed |
96 * with an async error containing the thrown value and a captured | 96 * with an async error containing the thrown value and a captured |
97 * stacktrace. | 97 * stacktrace. |
98 * | 98 * |
99 * However, if the result of calling [function] is already an asynchronous | 99 * However, if the result of calling [function] is already an asynchronous |
100 * result, we treat it specially. | 100 * result, we treat it specially. |
101 * | 101 * |
102 * If the returned value is itself a [Future], completion of | 102 * If the returned value is itself a [Future], completion of |
103 * the created future will wait until the returned future completes, | 103 * the created future will wait until the returned future completes, |
104 * and will then complete with the same result. | 104 * and will then complete with the same result. |
105 * | |
106 * If a thrown value is an [AsyncError], it is used directly as the result | |
107 * of the created future. | |
108 */ | 105 */ |
109 factory Future.of(function()) { | 106 factory Future.of(function()) { |
110 try { | 107 try { |
111 var result = function(); | 108 var result = function(); |
112 return new _FutureImpl<T>().._setOrChainValue(result); | 109 return new _FutureImpl<T>().._setOrChainValue(result); |
113 } catch (error, stackTrace) { | 110 } catch (error, stackTrace) { |
114 return new _FutureImpl<T>.immediateError(error, stackTrace); | 111 return new _FutureImpl<T>.immediateError(error, stackTrace); |
115 } | 112 } |
116 } | 113 } |
117 | 114 |
(...skipping 82 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
200 /** | 197 /** |
201 * When this future completes with a value, then [onValue] is called with this | 198 * When this future completes with a value, then [onValue] is called with this |
202 * value. If [this] future is already completed then the invocation of | 199 * value. If [this] future is already completed then the invocation of |
203 * [onValue] is delayed until the next event-loop iteration. | 200 * [onValue] is delayed until the next event-loop iteration. |
204 * | 201 * |
205 * Returns a new [Future] `f` which is completed with the result of | 202 * Returns a new [Future] `f` which is completed with the result of |
206 * invoking [onValue] (if [this] completes with a value) or [onError] (if | 203 * invoking [onValue] (if [this] completes with a value) or [onError] (if |
207 * [this] completes with an error). | 204 * [this] completes with an error). |
208 * | 205 * |
209 * If the invoked callback throws an exception, the returned future `f` is | 206 * If the invoked callback throws an exception, the returned future `f` is |
210 * completed with the error. If the value thrown is an [AsyncError], it is | 207 * completed with the error. |
211 * used directly, as the error result. Otherwise it is wrapped in an | |
212 * [AsyncError] first. | |
213 * | 208 * |
214 * If the invoked callback returns a [Future] `f2` then `f` and `f2` are | 209 * If the invoked callback returns a [Future] `f2` then `f` and `f2` are |
215 * chained. That is, `f` is completed with the completion value of `f2`. | 210 * chained. That is, `f` is completed with the completion value of `f2`. |
216 * | 211 * |
217 * If [onError] is not given, it is equivalent to `(e) { throw e; }`. That | 212 * If [onError] is not given, it is equivalent to `(e) { throw e; }`. That |
218 * is, it forwards the error to `f`. | 213 * is, it forwards the error to `f`. |
219 * | 214 * |
220 * In most cases, it is more readable to use [catchError] separately, possibly | 215 * In most cases, it is more readable to use [catchError] separately, possibly |
221 * with a `test` parameter, instead of handling both value and error in a | 216 * with a `test` parameter, instead of handling both value and error in a |
222 * single [then] call. | 217 * single [then] call. |
223 */ | 218 */ |
224 Future then(onValue(T value), { onError(AsyncError asyncError) }); | 219 Future then(onValue(T value), { onError(Object error) }); |
225 | 220 |
226 /** | 221 /** |
227 * Handles errors emitted by this [Future]. | 222 * Handles errors emitted by this [Future]. |
228 * | 223 * |
229 * Returns a new [Future] `f`. | 224 * Returns a new [Future] `f`. |
230 * | 225 * |
231 * When [this] completes with a value, the value is forwarded to `f` | 226 * When [this] completes with a value, the value is forwarded to `f` |
232 * unmodified. That is, `f` completes with the same value. | 227 * unmodified. That is, `f` completes with the same value. |
233 * | 228 * |
234 * When [this] completes with an error, [test] is called with the | 229 * When [this] completes with an error, [test] is called with the |
235 * error's value. If the invocation returns [true], [onError] is called with | 230 * error's value. If the invocation returns [true], [onError] is called with |
236 * the error wrapped in an [AsyncError]. The result of [onError] is handled | 231 * the error. The result of [onError] is handled exactly the same as for |
237 * exactly the same as for [then]'s [onError]. | 232 * [then]'s [onError]. |
238 * | 233 * |
239 * If [test] returns false, the exception is not handled by [onError], but is | 234 * If [test] returns false, the exception is not handled by [onError], but is |
240 * thrown unmodified, thus forwarding it to `f`. | 235 * thrown unmodified, thus forwarding it to `f`. |
241 * | 236 * |
242 * If [test] is omitted, it defaults to a function that always returns true. | 237 * If [test] is omitted, it defaults to a function that always returns true. |
243 * | 238 * |
244 * Example: | 239 * Example: |
245 * | 240 * |
246 * foo | 241 * foo |
247 * .catchError(..., test: (e) => e is ArgumentError) | 242 * .catchError(..., test: (e) => e is ArgumentError) |
248 * .catchError(..., test: (e) => e is NoSuchMethodError) | 243 * .catchError(..., test: (e) => e is NoSuchMethodError) |
249 * .then((v) { ... }); | 244 * .then((v) { ... }); |
250 * | 245 * |
251 * This method is equivalent to: | 246 * This method is equivalent to: |
252 * | 247 * |
253 * Future catchError(onError(AsyncError asyncError), | 248 * Future catchError(onError(error), |
254 * {bool test(Object error)}) { | 249 * {bool test(error)}) { |
255 * this.then((v) => v, // Forward the value. | 250 * this.then((v) => v, // Forward the value. |
256 * // But handle errors, if the [test] succeeds. | 251 * // But handle errors, if the [test] succeeds. |
257 * onError: (AsyncError e) { | 252 * onError: (e) { |
258 * if (test == null || test(e.error)) { | 253 * if (test == null || test(e)) { |
259 * return onError(e); | 254 * return onError(e); |
260 * } | 255 * } |
261 * throw e; | 256 * throw e; |
262 * }); | 257 * }); |
263 * } | 258 * } |
264 * | 259 * |
265 */ | 260 */ |
266 Future catchError(onError(AsyncError asyncError), | 261 Future catchError(onError(Object error), |
267 {bool test(Object error)}); | 262 {bool test(Object error)}); |
268 | 263 |
269 /** | 264 /** |
270 * Register a function to be called when this future completes. | 265 * Register a function to be called when this future completes. |
271 * | 266 * |
272 * The [action] function is called when this future completes, whether it | 267 * The [action] function is called when this future completes, whether it |
273 * does so with a value or with an error. | 268 * does so with a value or with an error. |
274 * | 269 * |
275 * This is the asynchronous equivalent of a "finally" block. | 270 * This is the asynchronous equivalent of a "finally" block. |
276 * | 271 * |
(...skipping 11 matching lines...) Expand all Loading... |
288 * ignored. | 283 * ignored. |
289 * | 284 * |
290 * This method is equivalent to: | 285 * This method is equivalent to: |
291 * | 286 * |
292 * Future<T> whenComplete(action()) { | 287 * Future<T> whenComplete(action()) { |
293 * this.then((v) { | 288 * this.then((v) { |
294 * var f2 = action(); | 289 * var f2 = action(); |
295 * if (f2 is Future) return f2.then((_) => v); | 290 * if (f2 is Future) return f2.then((_) => v); |
296 * return v | 291 * return v |
297 * }, | 292 * }, |
298 * onError: (AsyncError e) { | 293 * onError: (e) { |
299 * var f2 = action(); | 294 * var f2 = action(); |
300 * if (f2 is Future) return f2.then((_) { throw e; }); | 295 * if (f2 is Future) return f2.then((_) { throw e; }); |
301 * throw e; | 296 * throw e; |
302 * }); | 297 * }); |
303 * } | 298 * } |
304 */ | 299 */ |
305 Future<T> whenComplete(action()); | 300 Future<T> whenComplete(action()); |
306 | 301 |
307 /** | 302 /** |
308 * Creates a [Stream] that sends [this]' completion value, data or error, to | 303 * Creates a [Stream] that sends [this]' completion value, data or error, to |
(...skipping 36 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
345 */ | 340 */ |
346 void complete([T value]); | 341 void complete([T value]); |
347 | 342 |
348 /** | 343 /** |
349 * Complete [future] with an error. | 344 * Complete [future] with an error. |
350 * | 345 * |
351 * Completing a future with an error indicates that an exception was thrown | 346 * Completing a future with an error indicates that an exception was thrown |
352 * while trying to produce a value. | 347 * while trying to produce a value. |
353 * | 348 * |
354 * The argument [exception] should not be `null`. | 349 * The argument [exception] should not be `null`. |
355 * | |
356 * If [exception] is an [AsyncError], it is used directly as the error | |
357 * message sent to the future's listeners, and [stackTrace] is ignored. | |
358 * | |
359 * Otherwise the [exception] and an optional [stackTrace] is combined into an | |
360 * [AsyncError] and sent to this future's listeners. | |
361 */ | 350 */ |
362 void completeError(Object exception, [Object stackTrace]); | 351 void completeError(Object exception, [Object stackTrace]); |
363 | 352 |
364 /** | 353 /** |
365 * Whether the future has been completed. | 354 * Whether the future has been completed. |
366 */ | 355 */ |
367 bool get isCompleted; | 356 bool get isCompleted; |
368 } | 357 } |
OLD | NEW |