| 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 |