| OLD | NEW |
| 1 // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2011, 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) { |
| (...skipping 15 matching lines...) Expand all Loading... |
| 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 interface Future<T> default FutureImpl<T> { |
| 31 | 31 |
| 32 /** A future whose value is immediately available. */ | 32 /** A future whose value is immediately available. */ |
| 33 Future.immediate(T value); | 33 Future.immediate(T value); |
| 34 | 34 |
| 35 /** The value provided. Throws an exception if [hasValue] is false. */ | 35 /** The value provided. Throws an exception if [hasValue] is false. */ |
| 36 T get value(); | 36 T get value; |
| 37 | 37 |
| 38 /** | 38 /** |
| 39 * Exception that occurred ([:null:] if no exception occured). This property | 39 * Exception that occurred ([:null:] if no exception occured). This property |
| 40 * throws a [FutureNotCompleteException] if it is used before this future is | 40 * throws a [FutureNotCompleteException] if it is used before this future is |
| 41 * completes. | 41 * completes. |
| 42 */ | 42 */ |
| 43 Object get exception(); | 43 Object get exception; |
| 44 | 44 |
| 45 /** | 45 /** |
| 46 * The stack trace object associated with the exception that occurred. This | 46 * The stack trace object associated with the exception that occurred. This |
| 47 * throws a [FutureNotCompleteException] if it is used before the future | 47 * throws a [FutureNotCompleteException] if it is used before the future |
| 48 * completes. Returns [:null:] if the future completed successfully or a | 48 * completes. Returns [:null:] if the future completed successfully or a |
| 49 * stack trace wasn't provided with the exception when it occurred. | 49 * stack trace wasn't provided with the exception when it occurred. |
| 50 */ | 50 */ |
| 51 Object get stackTrace(); | 51 Object get stackTrace; |
| 52 | 52 |
| 53 /** | 53 /** |
| 54 * Whether the future is complete (either the value is available or there was | 54 * Whether the future is complete (either the value is available or there was |
| 55 * an exception). | 55 * an exception). |
| 56 */ | 56 */ |
| 57 bool get isComplete(); | 57 bool get isComplete; |
| 58 | 58 |
| 59 /** | 59 /** |
| 60 * Whether the value is available (meaning [isComplete] is true, and there was | 60 * Whether the value is available (meaning [isComplete] is true, and there was |
| 61 * no exception). | 61 * no exception). |
| 62 */ | 62 */ |
| 63 bool get hasValue(); | 63 bool get hasValue; |
| 64 | 64 |
| 65 /** | 65 /** |
| 66 * When this future is complete (either with a value or with an exception), | 66 * When this future is complete (either with a value or with an exception), |
| 67 * then [complete] is called with the future. | 67 * then [complete] is called with the future. |
| 68 * If [complete] throws an exception, it is ignored. | 68 * If [complete] throws an exception, it is ignored. |
| 69 */ | 69 */ |
| 70 void onComplete(void complete(Future<T> future)); | 70 void onComplete(void complete(Future<T> future)); |
| 71 | 71 |
| 72 /** | 72 /** |
| 73 * If this future is complete and has a value, then [onValue] is called | 73 * If this future is complete and has a value, then [onValue] is called |
| (...skipping 82 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 156 * // alternatively, if the service cannot produce the value, it | 156 * // alternatively, if the service cannot produce the value, it |
| 157 * // can provide an exception: | 157 * // can provide an exception: |
| 158 * completer.completeException(exception); | 158 * completer.completeException(exception); |
| 159 * | 159 * |
| 160 */ | 160 */ |
| 161 interface Completer<T> default CompleterImpl<T> { | 161 interface Completer<T> default CompleterImpl<T> { |
| 162 | 162 |
| 163 Completer(); | 163 Completer(); |
| 164 | 164 |
| 165 /** The future that will contain the value produced by this completer. */ | 165 /** The future that will contain the value produced by this completer. */ |
| 166 Future get future(); | 166 Future get future; |
| 167 | 167 |
| 168 /** Supply a value for [future]. */ | 168 /** Supply a value for [future]. */ |
| 169 void complete(T value); | 169 void complete(T value); |
| 170 | 170 |
| 171 /** | 171 /** |
| 172 * Indicate in [future] that an exception occured while trying to produce its | 172 * Indicate in [future] that an exception occured while trying to produce its |
| 173 * value. The argument [exception] should not be [:null:]. A [stackTrace] | 173 * value. The argument [exception] should not be [:null:]. A [stackTrace] |
| 174 * object can be provided as well to give the user information about where | 174 * object can be provided as well to give the user information about where |
| 175 * the error occurred. If omitted, it will be [:null:]. | 175 * the error occurred. If omitted, it will be [:null:]. |
| 176 */ | 176 */ |
| (...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 231 future.handleException((exception) { | 231 future.handleException((exception) { |
| 232 if (!result.isComplete) { | 232 if (!result.isComplete) { |
| 233 completer.completeException(exception, future.stackTrace); | 233 completer.completeException(exception, future.stackTrace); |
| 234 } | 234 } |
| 235 return true; | 235 return true; |
| 236 }); | 236 }); |
| 237 } | 237 } |
| 238 return result; | 238 return result; |
| 239 } | 239 } |
| 240 } | 240 } |
| OLD | NEW |