| 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 /** | 5 /** |
| 6 * A [Future] is used to obtain a value sometime in the future. Receivers of a | 6 * A [Future] is used to obtain a value sometime in the future. Receivers of a |
| 7 * [Future] can obtain the value by passing a callback to [then]. For example: | 7 * [Future] can obtain the value by passing a callback to [then]. For example: |
| 8 * | 8 * |
| 9 * Future<int> future = getFutureFromSomewhere(); | 9 * Future<int> future = getFutureFromSomewhere(); |
| 10 * future.then((value) { | 10 * future.then((value) { |
| 11 * print("I received the number $value"); | 11 * print("I received the number $value"); |
| 12 * }); | 12 * }); |
| 13 * | 13 * |
| 14 * A future may complete by *succeeding* (producing a value) or *failing* | 14 * A future may complete by *succeeding* (producing a value) or *failing* |
| 15 * (producing an exception, which may be handled with [handleException]). | 15 * (producing an exception, which may be handled with [handleException]). |
| 16 * Callbacks passed to [onComplete] will be invoked in either case. | 16 * Callbacks passed to [onComplete] will be invoked in either case. |
| 17 * | 17 * |
| 18 * When a future completes, the following actions happen in order: | 18 * When a future completes, the following actions happen in order: |
| 19 * | 19 * |
| 20 * 1. if the future suceeded, handlers registered with [then] are called. | 20 * 1. if the future suceeded, handlers registered with [then] are called. |
| 21 * 2. if the future failed, handlers registered with [handleException] are | 21 * 2. if the future failed, handlers registered with [handleException] are |
| 22 * called in sequence, until one returns true. | 22 * called in sequence, until one returns true. |
| 23 * 3. handlers registered with [onComplete] are called | 23 * 3. handlers registered with [onComplete] are called |
| 24 * 4. if the future failed, and at least one handler was registered with | 24 * 4. if the future failed, and at least one handler was registered with |
| 25 * [then], and no handler registered with [handleException] returned | 25 * [then], and no handler registered with [handleException] returned |
| 26 * [:true:], then the exception is thrown. | 26 * [:true:], then the exception is thrown. |
| 27 * | 27 * |
| 28 * Use a [Completer] to create and change the state of a [Future]. | 28 * Use a [Completer] to create and change the state of a [Future]. |
| 29 */ | 29 */ |
| 30 interface Future<T> default FutureImpl<T> { | 30 abstract class Future<T> { |
| 31 | |
| 32 /** A future whose value is immediately available. */ | 31 /** A future whose value is immediately available. */ |
| 33 Future.immediate(T value); | 32 factory Future.immediate(T value) => new FutureImpl<T>.immediate(value); |
| 34 | 33 |
| 35 /** The value provided. Throws an exception if [hasValue] is false. */ | 34 /** The value provided. Throws an exception if [hasValue] is false. */ |
| 36 T get value; | 35 T get value; |
| 37 | 36 |
| 38 /** | 37 /** |
| 39 * Exception that occurred ([:null:] if no exception occured). This property | 38 * Exception that occurred ([:null:] if no exception occured). This property |
| 40 * throws a [FutureNotCompleteException] if it is used before this future is | 39 * throws a [FutureNotCompleteException] if it is used before this future is |
| 41 * completes. | 40 * completes. |
| 42 */ | 41 */ |
| 43 Object get exception; | 42 Object get exception; |
| (...skipping 107 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 151 * ... | 150 * ... |
| 152 * | 151 * |
| 153 * // later when value is available, call: | 152 * // later when value is available, call: |
| 154 * completer.complete(value); | 153 * completer.complete(value); |
| 155 * | 154 * |
| 156 * // alternatively, if the service cannot produce the value, it | 155 * // alternatively, if the service cannot produce the value, it |
| 157 * // can provide an exception: | 156 * // can provide an exception: |
| 158 * completer.completeException(exception); | 157 * completer.completeException(exception); |
| 159 * | 158 * |
| 160 */ | 159 */ |
| 161 interface Completer<T> default CompleterImpl<T> { | 160 abstract class Completer<T> { |
| 162 | 161 |
| 163 Completer(); | 162 factory Completer() => new CompleterImpl<T>(); |
| 164 | 163 |
| 165 /** The future that will contain the value produced by this completer. */ | 164 /** The future that will contain the value produced by this completer. */ |
| 166 Future get future; | 165 Future get future; |
| 167 | 166 |
| 168 /** Supply a value for [future]. */ | 167 /** Supply a value for [future]. */ |
| 169 void complete(T value); | 168 void complete(T value); |
| 170 | 169 |
| 171 /** | 170 /** |
| 172 * Indicate in [future] that an exception occured while trying to produce its | 171 * Indicate in [future] that an exception occured while trying to produce its |
| 173 * value. The argument [exception] should not be [:null:]. A [stackTrace] | 172 * value. The argument [exception] should not be [:null:]. A [stackTrace] |
| (...skipping 17 matching lines...) Expand all Loading... |
| 191 FutureAlreadyCompleteException() {} | 190 FutureAlreadyCompleteException() {} |
| 192 String toString() => "Exception: future already completed"; | 191 String toString() => "Exception: future already completed"; |
| 193 } | 192 } |
| 194 | 193 |
| 195 | 194 |
| 196 /** | 195 /** |
| 197 * [Futures] holds additional utility functions that operate on [Future]s (for | 196 * [Futures] holds additional utility functions that operate on [Future]s (for |
| 198 * example, waiting for a collection of Futures to complete). | 197 * example, waiting for a collection of Futures to complete). |
| 199 */ | 198 */ |
| 200 class Futures { | 199 class Futures { |
| 201 | |
| 202 /** | 200 /** |
| 203 * Returns a future which will complete once all the futures in a list are | 201 * Returns a future which will complete once all the futures in a list are |
| 204 * complete. If any of the futures in the list completes with an exception, | 202 * complete. If any of the futures in the list completes with an exception, |
| 205 * the resulting future also completes with an exception. (The value of the | 203 * the resulting future also completes with an exception. (The value of the |
| 206 * returned future will be a list of all the values that were produced.) | 204 * returned future will be a list of all the values that were produced.) |
| 207 */ | 205 */ |
| 208 static Future<List> wait(List<Future> futures) { | 206 static Future<List> wait(List<Future> futures) { |
| 209 if (futures.isEmpty()) { | 207 if (futures.isEmpty()) { |
| 210 return new Future<List>.immediate(const []); | 208 return new Future<List>.immediate(const []); |
| 211 } | 209 } |
| (...skipping 19 matching lines...) Expand all Loading... |
| 231 future.handleException((exception) { | 229 future.handleException((exception) { |
| 232 if (!result.isComplete) { | 230 if (!result.isComplete) { |
| 233 completer.completeException(exception, future.stackTrace); | 231 completer.completeException(exception, future.stackTrace); |
| 234 } | 232 } |
| 235 return true; | 233 return true; |
| 236 }); | 234 }); |
| 237 } | 235 } |
| 238 return result; | 236 return result; |
| 239 } | 237 } |
| 240 } | 238 } |
| OLD | NEW |