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 |
(...skipping 24 matching lines...) Expand all Loading... |
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 |
39 * makes sure that no error is silently dropped. However, it also means that | 39 * makes sure that no error is silently dropped. However, it also means that |
40 * error handlers should be installed early, so that they are present as soon | 40 * error handlers should be installed early, so that they are present as soon |
41 * as a future is completed with an error. The following example demonstrates | 41 * as a future is completed with an error. The following example demonstrates |
42 * this potential bug: | 42 * this potential bug: |
43 * | 43 * |
44 * var future = getFuture(); | 44 * var future = getFuture(); |
45 * new Timer(5, (_) { | 45 * new Timer(new Duration(milliseconds: 5), () { |
46 * // The error-handler is only attached 5ms after the future has been | 46 * // The error-handler is only attached 5ms after the future has been |
47 * // received. If the future fails in the mean-time it will forward the | 47 * // received. If the future fails in the mean-time it will forward the |
48 * // error to the global error-handler, even though there is code (just | 48 * // error to the global error-handler, even though there is code (just |
49 * // below) to handle the error. | 49 * // below) to handle the error. |
50 * future.then((value) { useValue(value); }, | 50 * future.then((value) { useValue(value); }, |
51 * onError: (e) { handleError(e); }); | 51 * onError: (e) { handleError(e); }); |
52 * }); | 52 * }); |
53 * | 53 * |
54 * In general we discourage registering the two callbacks at the same time, but | 54 * In general we discourage registering the two callbacks at the same time, but |
55 * prefer to use [then] with one argument (the value handler), and to use | 55 * prefer to use [then] with one argument (the value handler), and to use |
(...skipping 290 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
346 * The argument [exception] should not be `null`. | 346 * The argument [exception] should not be `null`. |
347 * | 347 * |
348 * If [exception] is an [AsyncError], it is used directly as the error | 348 * If [exception] is an [AsyncError], it is used directly as the error |
349 * message sent to the future's listeners, and [stackTrace] is ignored. | 349 * message sent to the future's listeners, and [stackTrace] is ignored. |
350 * | 350 * |
351 * Otherwise the [exception] and an optional [stackTrace] is combined into an | 351 * Otherwise the [exception] and an optional [stackTrace] is combined into an |
352 * [AsyncError] and sent to this future's listeners. | 352 * [AsyncError] and sent to this future's listeners. |
353 */ | 353 */ |
354 void completeError(Object exception, [Object stackTrace]); | 354 void completeError(Object exception, [Object stackTrace]); |
355 } | 355 } |
OLD | NEW |