Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(289)

Side by Side Diff: sdk/lib/async/future.dart

Issue 14251006: Remove AsyncError with Expando. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Address comments. Created 7 years, 8 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « sdk/lib/async/async_error.dart ('k') | sdk/lib/async/future_impl.dart » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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
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
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
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 }
OLDNEW
« no previous file with comments | « sdk/lib/async/async_error.dart ('k') | sdk/lib/async/future_impl.dart » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698