mirror of
https://github.com/dart-lang/sdk
synced 2024-09-16 02:57:35 +00:00
Clean-up of Future documentation and small fix-ups.
R=floitsch@google.com Review-Url: https://codereview.chromium.org/2917683002 .
This commit is contained in:
parent
eefdf15aa1
commit
2a14e68d78
|
@ -57,28 +57,38 @@ abstract class FutureOr<T> {
|
|||
* future.then((value) => handleValue(value))
|
||||
* .catchError((error) => handleError(error));
|
||||
*
|
||||
* A [Future] can complete in two ways:
|
||||
* A [Future] can be completed in two ways:
|
||||
* with a value ("the future succeeds")
|
||||
* or with an error ("the future fails").
|
||||
* Users can install callbacks for each case.
|
||||
*
|
||||
* In some cases we say that a future is completed with another future.
|
||||
* This is a short way of stating that the future is completed in the same way,
|
||||
* with the same value or error,
|
||||
* as the other future once that completes.
|
||||
* Whenever a function in the core library may complete a future
|
||||
* (for example [Completer.complete] or [new Future.value]),
|
||||
* then it also accepts another future and does this work for the developer.
|
||||
*
|
||||
* The result of registering a pair of callbacks is a new Future (the
|
||||
* "successor") which in turn is completed with the result of invoking the
|
||||
* corresponding callback.
|
||||
* The successor is completed with an error if the invoked callback throws.
|
||||
* For example:
|
||||
*
|
||||
* Future<int> successor = future.then((int value) {
|
||||
* // Invoked when the future is completed with a value.
|
||||
* return 42; // The successor is completed with the value 42.
|
||||
* },
|
||||
* onError: (e) {
|
||||
* // Invoked when the future is completed with an error.
|
||||
* if (canHandle(e)) {
|
||||
* return 499; // The successor is completed with the value 499.
|
||||
* } else {
|
||||
* throw e; // The successor is completed with the error e.
|
||||
* }
|
||||
* });
|
||||
* ```
|
||||
* Future<int> successor = future.then((int value) {
|
||||
* // Invoked when the future is completed with a value.
|
||||
* return 42; // The successor is completed with the value 42.
|
||||
* },
|
||||
* onError: (e) {
|
||||
* // Invoked when the future is completed with an error.
|
||||
* if (canHandle(e)) {
|
||||
* return 499; // The successor is completed with the value 499.
|
||||
* } else {
|
||||
* throw e; // The successor is completed with the error e.
|
||||
* }
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* If a future does not have a successor when it completes with an error,
|
||||
* it forwards the error message to the global error-handler.
|
||||
|
@ -86,16 +96,17 @@ abstract class FutureOr<T> {
|
|||
* However, it also means that error handlers should be installed early,
|
||||
* so that they are present as soon as a future is completed with an error.
|
||||
* The following example demonstrates this potential bug:
|
||||
*
|
||||
* var future = getFuture();
|
||||
* new Timer(new Duration(milliseconds: 5), () {
|
||||
* // The error-handler is not attached until 5 ms after the future has
|
||||
* // been received. If the future fails before that, the error is
|
||||
* // forwarded to the global error-handler, even though there is code
|
||||
* // (just below) to eventually handle the error.
|
||||
* future.then((value) { useValue(value); },
|
||||
* onError: (e) { handleError(e); });
|
||||
* });
|
||||
* ```
|
||||
* var future = getFuture();
|
||||
* new Timer(new Duration(milliseconds: 5), () {
|
||||
* // The error-handler is not attached until 5 ms after the future has
|
||||
* // been received. If the future fails before that, the error is
|
||||
* // forwarded to the global error-handler, even though there is code
|
||||
* // (just below) to eventually handle the error.
|
||||
* future.then((value) { useValue(value); },
|
||||
* onError: (e) { handleError(e); });
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* When registering callbacks, it's often more readable to register the two
|
||||
* callbacks separately, by first using [then] with one argument
|
||||
|
@ -107,20 +118,22 @@ abstract class FutureOr<T> {
|
|||
* Using sequential handlers instead of parallel ones often leads to code that
|
||||
* is easier to reason about.
|
||||
* It also makes asynchronous code very similar to synchronous code:
|
||||
*
|
||||
* // Synchronous code.
|
||||
* try {
|
||||
* int value = foo();
|
||||
* return bar(value);
|
||||
* } catch (e) {
|
||||
* return 499;
|
||||
* }
|
||||
* ```
|
||||
* // Synchronous code.
|
||||
* try {
|
||||
* int value = foo();
|
||||
* return bar(value);
|
||||
* } catch (e) {
|
||||
* return 499;
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* Equivalent asynchronous code, based on futures:
|
||||
*
|
||||
* Future<int> future = new Future(foo); // Result of foo() as a future.
|
||||
* future.then((int value) => bar(value))
|
||||
* .catchError((e) => 499);
|
||||
* ```
|
||||
* Future<int> future = new Future(foo); // Result of foo() as a future.
|
||||
* future.then((int value) => bar(value))
|
||||
* .catchError((e) => 499);
|
||||
* ```
|
||||
*
|
||||
* Similar to the synchronous code, the error handler (registered with
|
||||
* [catchError]) is handling any errors thrown by either `foo` or `bar`.
|
||||
|
@ -134,9 +147,12 @@ abstract class FutureOr<T> {
|
|||
* called.
|
||||
*/
|
||||
abstract class Future<T> {
|
||||
// The `_nullFuture` is a completed Future with the value `null`.
|
||||
/// A `Future<Null>` completed with `null`.
|
||||
static final _Future<Null> _nullFuture = new _Future<Null>.value(null);
|
||||
|
||||
/// A `Future<bool>` completed with `false`.
|
||||
static final _Future<bool> _falseFuture = new _Future<bool>.value(false);
|
||||
|
||||
/**
|
||||
* Creates a future containing the result of calling [computation]
|
||||
* asynchronously with [Timer.run].
|
||||
|
@ -226,19 +242,30 @@ abstract class Future<T> {
|
|||
}
|
||||
|
||||
/**
|
||||
* A future whose value is available in the next event-loop iteration.
|
||||
* Creates a future completed with [value].
|
||||
*
|
||||
* If [result] is not a [Future], using this constructor is equivalent
|
||||
* to `new Future<T>.sync(() => result)`.
|
||||
* If [value] is a future, the created future waits for the
|
||||
* [value] future to complete, and then completes with the same result.
|
||||
* Since a [value] future can complete with an error, so can the future
|
||||
* created by [Future.value], even if the name suggests otherwise.
|
||||
*
|
||||
* If [value] is not a [Future], the created future is completed
|
||||
* with the [value] value,
|
||||
* equivalently to `new Future<T>.sync(() => value)`.
|
||||
*
|
||||
* Use [Completer] to create a future and complete it later.
|
||||
*/
|
||||
factory Future.value([FutureOr<T> result]) {
|
||||
return new _Future<T>.immediate(result);
|
||||
factory Future.value([FutureOr<T> value]) {
|
||||
return new _Future<T>.immediate(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* A future that completes with an error in the next event-loop iteration.
|
||||
* Creates a future that completes with an error.
|
||||
*
|
||||
* The created future will be completed with an error in a future microtask.
|
||||
* This allows enough time for someone to add an error handler on the future.
|
||||
* If an error handler isn't added before the future completes, the error
|
||||
* will be considered unhandled.
|
||||
*
|
||||
* If [error] is `null`, it is replaced by a [NullThrownError].
|
||||
*
|
||||
|
@ -260,12 +287,14 @@ abstract class Future<T> {
|
|||
* Creates a future that runs its computation after a delay.
|
||||
*
|
||||
* The [computation] will be executed after the given [duration] has passed,
|
||||
* and the future is completed with the result.
|
||||
* and the future is completed with the result of the computation,
|
||||
*
|
||||
* If the duration is 0 or less,
|
||||
* it completes no sooner than in the next event-loop iteration.
|
||||
* it completes no sooner than in the next event-loop iteration,
|
||||
* after all microtasks have run.
|
||||
*
|
||||
* If [computation] is omitted,
|
||||
* it will be treated as if [computation] was set to `() => null`,
|
||||
* it will be treated as if [computation] was `() => null`,
|
||||
* and the future will eventually complete with the `null` value.
|
||||
*
|
||||
* If calling [computation] throws, the created future will complete with the
|
||||
|
@ -287,17 +316,18 @@ abstract class Future<T> {
|
|||
}
|
||||
|
||||
/**
|
||||
* Wait for all the given futures to complete and collect their values.
|
||||
* Waits for multiple futures to complete and collects their results.
|
||||
*
|
||||
* Returns a future which will complete once all the futures in a list
|
||||
* have completed.
|
||||
* Returns a future which will complete once all the provided futures
|
||||
* have completed, either with their results, or with an error if either
|
||||
* of the provided futures fail.
|
||||
*
|
||||
* The value of the returned future will be a list of all the values that
|
||||
* were produced.
|
||||
*
|
||||
* If any of the given futures completes with an error, then the returned
|
||||
* future completes with that error. If other futures complete with errors,
|
||||
* those errors are discarded.
|
||||
* If any future completes with an error,
|
||||
* then the returned future completes with that error.
|
||||
* If further futures also complete with errors, those errors are discarded.
|
||||
*
|
||||
* If `eagerError` is true, the returned future completes with an error
|
||||
* immediately on the first error from one of the futures. Otherwise all
|
||||
|
@ -310,7 +340,7 @@ abstract class Future<T> {
|
|||
* lost (since the returned future does not provide access to these values).
|
||||
* The [cleanUp] function is unused if there is no error.
|
||||
*
|
||||
* The call to `cleanUp` should not throw. If it does, the error will be an
|
||||
* The call to [cleanUp] should not throw. If it does, the error will be an
|
||||
* uncaught asynchronous error.
|
||||
*/
|
||||
static Future<List<T>> wait<T>(Iterable<Future<T>> futures,
|
||||
|
@ -408,7 +438,8 @@ abstract class Future<T> {
|
|||
* Returns the result of the first future in [futures] to complete.
|
||||
*
|
||||
* The returned future is completed with the result of the first
|
||||
* future in [futures] to report that it is complete.
|
||||
* future in [futures] to report that it is complete,
|
||||
* whether it's with a value or an error.
|
||||
* The results of all the other futures are discarded.
|
||||
*
|
||||
* If [futures] is empty, or if none of its futures complete,
|
||||
|
@ -429,13 +460,13 @@ abstract class Future<T> {
|
|||
}
|
||||
|
||||
/**
|
||||
* Perform an operation for each element of the iterable, in turn.
|
||||
* Performs an action for each element of the iterable, in turn.
|
||||
*
|
||||
* The operation, [f], may be either synchronous or asynchronous.
|
||||
* The [action] may be either synchronous or asynchronous.
|
||||
*
|
||||
* Calls [f] with each element in [input] in order.
|
||||
* If the call to [f] returns a `Future<T>`, the iteration waits
|
||||
* until the future is completed before moving to the next element.
|
||||
* Calls [action] with each element in [elements] in order.
|
||||
* If the call to [action] returns a `Future<T>`, the iteration waits
|
||||
* until the future is completed before continuing with the next element.
|
||||
*
|
||||
* Returns a [Future] that completes with `null` when all elements have been
|
||||
* processed.
|
||||
|
@ -443,14 +474,14 @@ abstract class Future<T> {
|
|||
* Non-[Future] return values, and completion-values of returned [Future]s,
|
||||
* are discarded.
|
||||
*
|
||||
* Any error from [f], synchronous or asynchronous, will stop the iteration
|
||||
* and will be reported in the returned [Future].
|
||||
* Any error from [action], synchronous or asynchronous,
|
||||
* will stop the iteration and be reported in the returned [Future].
|
||||
*/
|
||||
static Future forEach<T>(Iterable<T> input, FutureOr f(T element)) {
|
||||
var iterator = input.iterator;
|
||||
static Future forEach<T>(Iterable<T> elements, FutureOr action(T element)) {
|
||||
var iterator = elements.iterator;
|
||||
return doWhile(() {
|
||||
if (!iterator.moveNext()) return false;
|
||||
var result = f(iterator.current);
|
||||
var result = action(iterator.current);
|
||||
if (result is Future) return result.then(_kTrue);
|
||||
return true;
|
||||
});
|
||||
|
@ -475,12 +506,13 @@ abstract class Future<T> {
|
|||
* an error, iteration ends and the future returned by [doWhile]
|
||||
* completes with the same error.
|
||||
*
|
||||
* Calls to [f] may happen at any time, including immediately after calling
|
||||
* `doWhile`. The only restriction is a new call to [f] won't happen before
|
||||
* Calls to [action] may happen at any time,
|
||||
* including immediately after calling `doWhile`.
|
||||
* The only restriction is a new call to [action] won't happen before
|
||||
* the previous call has returned, and if it returned a `Future<bool>`, not
|
||||
* until that future has completed.
|
||||
*/
|
||||
static Future doWhile(FutureOr<bool> f()) {
|
||||
static Future doWhile(FutureOr<bool> action()) {
|
||||
_Future doneSignal = new _Future();
|
||||
var nextIteration;
|
||||
// Bind this callback explicitly so that each iteration isn't bound in the
|
||||
|
@ -491,7 +523,7 @@ abstract class Future<T> {
|
|||
while (keepGoing) {
|
||||
FutureOr<bool> result;
|
||||
try {
|
||||
result = f();
|
||||
result = action();
|
||||
} catch (error, stackTrace) {
|
||||
// Cannot use _completeWithErrorCallback because it completes
|
||||
// the future synchronously.
|
||||
|
@ -587,31 +619,6 @@ abstract class Future<T> {
|
|||
* added. If the first `catchError` (or `then`) call happens after this future
|
||||
* has completed with an error then the error is reported as unhandled error.
|
||||
* See the description on [Future].
|
||||
*
|
||||
* Example:
|
||||
*
|
||||
* foo
|
||||
* .catchError(..., test: (e) => e is ArgumentError)
|
||||
* .catchError(..., test: (e) => e is NoSuchMethodError)
|
||||
* .then((v) { ... });
|
||||
*
|
||||
* This method is equivalent to:
|
||||
*
|
||||
* Future catchError(onError(error),
|
||||
* {bool test(error)}) {
|
||||
* this.then((v) => v, // Forward the value.
|
||||
* // But handle errors, if the [test] succeeds.
|
||||
* onError: (e, stackTrace) {
|
||||
* if (test == null || test(e)) {
|
||||
* if (onError is ZoneBinaryCallback) {
|
||||
* return onError(e, stackTrace);
|
||||
* }
|
||||
* return onError(e);
|
||||
* }
|
||||
* throw e;
|
||||
* });
|
||||
* }
|
||||
*
|
||||
*/
|
||||
// The `Function` below stands for one of two types:
|
||||
// - (dynamic) -> FutureOr<T>
|
||||
|
@ -623,7 +630,7 @@ abstract class Future<T> {
|
|||
Future<T> catchError(Function onError, {bool test(Object error)});
|
||||
|
||||
/**
|
||||
* Register a function to be called when this future completes.
|
||||
* Registers a function to be called when this future completes.
|
||||
*
|
||||
* The [action] function is called when this future completes, whether it
|
||||
* does so with a value or with an error.
|
||||
|
@ -713,41 +720,42 @@ class TimeoutException implements Exception {
|
|||
* Most of the time, the simplest way to create a future is to just use
|
||||
* one of the [Future] constructors to capture the result of a single
|
||||
* asynchronous computation:
|
||||
*
|
||||
* new Future(() { doSomething(); return result; });
|
||||
*
|
||||
* ```
|
||||
* new Future(() { doSomething(); return result; });
|
||||
* ```
|
||||
* or, if the future represents the result of a sequence of asynchronous
|
||||
* computations, they can be chained using [Future.then] or similar functions
|
||||
* on [Future]:
|
||||
*
|
||||
* Future doStuff(){
|
||||
* return someAsyncOperation().then((result) {
|
||||
* return someOtherAsyncOperation(result);
|
||||
* });
|
||||
* }
|
||||
*
|
||||
* ```
|
||||
* Future doStuff(){
|
||||
* return someAsyncOperation().then((result) {
|
||||
* return someOtherAsyncOperation(result);
|
||||
* });
|
||||
* }
|
||||
* ```
|
||||
* If you do need to create a Future from scratch — for example,
|
||||
* when you're converting a callback-based API into a Future-based
|
||||
* one — you can use a Completer as follows:
|
||||
* ```
|
||||
* class AsyncOperation {
|
||||
* Completer _completer = new Completer();
|
||||
*
|
||||
* class AsyncOperation {
|
||||
* Completer _completer = new Completer();
|
||||
* Future<T> doOperation() {
|
||||
* _startOperation();
|
||||
* return _completer.future; // Send future object back to client.
|
||||
* }
|
||||
*
|
||||
* Future<T> doOperation() {
|
||||
* _startOperation();
|
||||
* return _completer.future; // Send future object back to client.
|
||||
* }
|
||||
* // Something calls this when the value is ready.
|
||||
* void _finishOperation(T result) {
|
||||
* _completer.complete(result);
|
||||
* }
|
||||
*
|
||||
* // Something calls this when the value is ready.
|
||||
* void _finishOperation(T result) {
|
||||
* _completer.complete(result);
|
||||
* }
|
||||
*
|
||||
* // If something goes wrong, call this.
|
||||
* void _errorHappened(error) {
|
||||
* _completer.completeError(error);
|
||||
* }
|
||||
* }
|
||||
* // If something goes wrong, call this.
|
||||
* void _errorHappened(error) {
|
||||
* _completer.completeError(error);
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
abstract class Completer<T> {
|
||||
/**
|
||||
|
@ -758,17 +766,18 @@ abstract class Completer<T> {
|
|||
* either [complete] or [completeError].
|
||||
*
|
||||
* The completer completes the future asynchronously. That means that
|
||||
* callbacks registered on the future, are not called immediately when
|
||||
* callbacks registered on the future are not called immediately when
|
||||
* [complete] or [completeError] is called. Instead the callbacks are
|
||||
* delayed until a later microtask.
|
||||
*
|
||||
* Example:
|
||||
*
|
||||
* var completer = new Completer();
|
||||
* handOut(completer.future);
|
||||
* later: {
|
||||
* completer.complete('completion value');
|
||||
* }
|
||||
* ```
|
||||
* var completer = new Completer();
|
||||
* handOut(completer.future);
|
||||
* later: {
|
||||
* completer.complete('completion value');
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
factory Completer() => new _AsyncCompleter<T>();
|
||||
|
||||
|
@ -824,7 +833,11 @@ abstract class Completer<T> {
|
|||
*/
|
||||
factory Completer.sync() => new _SyncCompleter<T>();
|
||||
|
||||
/** The future that will contain the result provided to this completer. */
|
||||
/**
|
||||
* The future that is completed by this completer.
|
||||
*
|
||||
* The future that is completed when [complete] or [completeError] is called.
|
||||
*/
|
||||
Future<T> get future;
|
||||
|
||||
/**
|
||||
|
@ -837,7 +850,7 @@ abstract class Completer<T> {
|
|||
* to complete, and complete with the same result, whether it is a success
|
||||
* or an error.
|
||||
*
|
||||
* Calling `complete` or [completeError] must not be done more than once.
|
||||
* Calling [complete] or [completeError] must be done at most once.
|
||||
*
|
||||
* All listeners on the future are informed about the value.
|
||||
*/
|
||||
|
@ -846,7 +859,7 @@ abstract class Completer<T> {
|
|||
/**
|
||||
* Complete [future] with an error.
|
||||
*
|
||||
* Calling [complete] or `completeError` must not be done more than once.
|
||||
* Calling [complete] or [completeError] must be done at most once.
|
||||
*
|
||||
* Completing a future with an error indicates that an exception was thrown
|
||||
* while trying to produce a value.
|
||||
|
@ -855,18 +868,27 @@ abstract class Completer<T> {
|
|||
*
|
||||
* If `error` is a `Future`, the future itself is used as the error value.
|
||||
* If you want to complete with the result of the future, you can use:
|
||||
*
|
||||
* thisCompleter.complete(theFuture)
|
||||
*
|
||||
* ```
|
||||
* thisCompleter.complete(theFuture)
|
||||
* ```
|
||||
* or if you only want to handle an error from the future:
|
||||
*
|
||||
* theFuture.catchError(thisCompleter.completeError);
|
||||
*
|
||||
* ```
|
||||
* theFuture.catchError(thisCompleter.completeError);
|
||||
* ```
|
||||
*/
|
||||
void completeError(Object error, [StackTrace stackTrace]);
|
||||
|
||||
/**
|
||||
* Whether the future has been completed.
|
||||
* Whether the [future] has been completed.
|
||||
*
|
||||
* Reflects whether [complete] or [completeError] has been called.
|
||||
* A `true` value doesn't necessarily mean that listeners of this future
|
||||
* have been invoked yet, either because the completer usually waits until
|
||||
* a later microtask to propagate the result, or because [complete]
|
||||
* was called with a future that hasn't completed yet.
|
||||
*
|
||||
* When this value is `true`, [complete] and [completeError] must not be
|
||||
* called again.
|
||||
*/
|
||||
bool get isCompleted;
|
||||
}
|
||||
|
@ -882,7 +904,7 @@ void _completeWithErrorCallback(_Future result, error, stackTrace) {
|
|||
result._completeError(error, stackTrace);
|
||||
}
|
||||
|
||||
// Like [_completeWIthErrorCallback] but completes asynchronously.
|
||||
// Like [_completeWithErrorCallback] but completes asynchronously.
|
||||
void _asyncCompleteWithErrorCallback(_Future result, error, stackTrace) {
|
||||
AsyncError replacement = Zone.current.errorCallback(error, stackTrace);
|
||||
if (replacement != null) {
|
||||
|
|
|
@ -560,12 +560,12 @@ abstract class Stream<T> {
|
|||
*
|
||||
* Returns a new stream where each element of this stream is replaced
|
||||
* by zero or more data events.
|
||||
* The event values are proveded as an [Iterable] by a call to [convert]
|
||||
* The event values are provided as an [Iterable] by a call to [convert]
|
||||
* with the element as argument, and the elements of that iterable is
|
||||
* emitted in iteration order.
|
||||
* If calling [convert] throws, or if iteration of the returned values throws,
|
||||
* the error is emitted on the returned stream and iteration ends for that
|
||||
* element of this stream.
|
||||
* If calling [convert] throws, or if the iteration of the returned values
|
||||
* throws, the error is emitted on the returned stream and iteration ends
|
||||
* for that element of this stream.
|
||||
*
|
||||
* Error events and the done event of this stream are forwarded directly
|
||||
* to the returned stream.
|
||||
|
|
|
@ -996,7 +996,7 @@ class _StreamIterator<T> implements StreamIterator<T> {
|
|||
_stateData = future;
|
||||
return future;
|
||||
}
|
||||
return new _Future<bool>.immediate(false);
|
||||
return Future._falseFuture;
|
||||
}
|
||||
|
||||
Future cancel() {
|
||||
|
|
Loading…
Reference in a new issue