fix #28008, fix #28009 implement FutureOr<T>

pkg/dev_compiler/tool/input_sdk/lib/async/future.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.async;
 
+/// A type representing values that are either `Future<T>` or `T`.
+///
+/// This class declaration is a public stand-in for an internal
+/// future-or-value generic type. References to this class are resolved to the
+/// internal type.
+///
+/// It is a compile-time error for any class to extend, mix in or implement
+/// `FutureOr`.
+///
+/// Note: the `FutureOr<T>` type is interpreted as `dynamic` in non strong-mode.
+///
+/// # Examples
+/// ``` dart
+/// // The `Future<T>.then` function takes a callback [f] that returns either
+/// // an `S` or a `Future<S>`.
+/// Future<S> then<S>(FutureOr<S> f(T x), ...);
+///
+/// // `Completer<T>.complete` takes either a `T` or `Future<T>`.
+/// void complete(FutureOr<T> value);
+/// ```
+///
+/// # Advanced
+/// The `FutureOr<int>` type is actually the "type union" of the types `int` and
+/// `Future<int>`. This type union is defined in such a way that
+/// `FutureOr<Object>` is both a super- and sub-type of `Object` (sub-type
+/// because `Object` is one of the types of the union, super-type because
+/// `Object` is a super-type of both of the types of the union). Together it
+/// means that `FutureOr<Object>` is equivalent to `Object`.
+///
+/// As a corollary, `FutureOr<Object>` is equivalent to
+/// `FutureOr<FutureOr<Object>>`, `FutureOr<Future<Object>> is equivalent to
+/// `Future<Object>`.
+abstract class FutureOr<T> {
+  // Private constructor, so that it is not subclassable, mixable, or
+  // instantiable.
+  FutureOr._() {
+    throw new UnsupportedError("FutureOr can't be instantiated");
+  }
+}
+
 /**
  * An object representing a delayed computation.
  *
  * A [Future] is used to represent a potential value, or error,
  * that will be available at some time in the future.
  * Receivers of a [Future] can register callbacks
  * that handle the value or error once it is available.
  * For example:
  *
  *     Future<int> future = getFuture();
@@ skipping 201 matching lines @@
    * If calling [computation] throws, the created future will complete with the
    * error.
    *
    * See also [Completer] for a way to create and complete a future at a
    * later time that isn't necessarily after a known fixed duration.
    */
   factory Future.delayed(Duration duration, [computation()]) {
     _Future<T> result = new _Future<T>();
     new Timer(duration, () {
       try {
-        result._complete(computation == null ? null : computation());
+        result._complete(computation?.call());
       } catch (e, s) {
         _completeWithErrorCallback(result, e, s);
       }
     });
     return result;
   }
 
   /**
    * Wait for all the given futures to complete and collect their values.
    *
    * Returns a future which will complete once all the futures in a list are
    * complete. If any of the futures in the list completes with an error,
    * the resulting future also completes with an error. Otherwise the value
    * of the returned future will be a list of all the values that were
    * produced.
    *
    * If `eagerError` is true, the future completes with an error immediately on
    * the first error from one of the futures. Otherwise all futures must
    * complete before the returned future is completed (still with the first
    * error to occur, the remaining errors are silently dropped).
    *
    * If [cleanUp] is provided, in the case of an error, any non-null result of
    * a successful future is passed to `cleanUp`, which can then release any
    * resources that the successful operation allocated.
    *
    * 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,
+  static Future<List<T>> wait<T>(Iterable<Future<T>> futures,
                            {bool eagerError: false,
-                            void cleanUp(/*=T*/ successValue)}) {
-    final _Future<List/*<T>*/> result = new _Future<List/*<T>*/>();
-    List/*<T>*/ values;  // Collects the values. Set to null on error.
+                            void cleanUp(T successValue)}) {
+    final _Future<List<T>> result = new _Future<List<T>>();
+    List<T> values;  // Collects the values. Set to null on error.
     int remaining = 0;  // How many futures are we waiting for.
     var error;   // The first error from a future.
     StackTrace stackTrace;  // The stackTrace that came with the error.
 
     // Handle an error from any of the futures.
     void handleError(theError, theStackTrace) {
       remaining--;
       if (values != null) {
         if (cleanUp != null) {
           for (var value in values) {
             if (value != null) {
               // Ensure errors from cleanUp are uncaught.
               new Future.sync(() { cleanUp(value); });
             }
           }
         }
         values = null;
         if (remaining == 0 || eagerError) {
           result._completeError(theError, theStackTrace);
         } else {
           error = theError;
           stackTrace = theStackTrace;
         }
       } else if (remaining == 0 && !eagerError) {
         result._completeError(error, stackTrace);
       }
     }
 
-    // As each future completes, put its value into the corresponding
-    // position in the list of values.
-    for (Future future in futures) {
-      int pos = remaining++;
-      future.then((Object/*=T*/ value) {
-        remaining--;
-        if (values != null) {
-          values[pos] = value;
-          if (remaining == 0) {
-            result._completeWithValue(values);
+    try {
+      // As each future completes, put its value into the corresponding
+      // position in the list of values.
+      for (Future future in futures) {
+        int pos = remaining;
+        future.then((T value) {
+          remaining--;
+          if (values != null) {
+            values[pos] = value;
+            if (remaining == 0) {
+              result._completeWithValue(values);
+            }
+          } else {
+            if (cleanUp != null && value != null) {
+              // Ensure errors from cleanUp are uncaught.
+              new Future.sync(() { cleanUp(value); });
+            }
+            if (remaining == 0 && !eagerError) {
+              result._completeError(error, stackTrace);
+            }
           }
-        } else {
-          if (cleanUp != null && value != null) {
-            // Ensure errors from cleanUp are uncaught.
-            new Future.sync(() { cleanUp(value); });
-          }
-          if (remaining == 0 && !eagerError) {
-            result._completeError(error, stackTrace);
-          }
-        }
-      }, onError: handleError);
+        }, onError: handleError);
+        // Increment the 'remaining' after the call to 'then'.
+        // If that call throws, we don't expect any future callback from
+        // the future, and we also don't increment remaining.
+        remaining++;
+      }
+      if (remaining == 0) {
+        return new Future.value(const []);
+      }
+      values = new List<T>(remaining);
+    } catch (e, st) {
+      // The error must have been thrown while iterating over the futures
+      // list, or while installing a callback handler on the future.
+      if (remaining == 0 || eagerError) {
+        // Throw a new Future.error.
+        // Don't just call `result._completeError` since that would propagate
+        // the error too eagerly, not giving the callers time to install
+        // error handlers.
+        // Also, don't use `_asyncCompleteError` since that one doesn't give
+        // zones the chance to intercept the error.
+        return new Future.error(e, st);
+      } else {
+        // Don't allocate a list for values, thus indicating that there was an
+        // error.
+        // Set error to the caught exception.
+        error = e;
+        stackTrace = st;
+      }
     }
-    if (remaining == 0) {
-      return new Future.value(const []);
-    }
-    values = new List/*<T>*/(remaining);
     return result;
   }
 
   /**
    * 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.
    * The results of all the other futures are discarded.
    *
    * If [futures] is empty, or if none of its futures complete,
    * the returned future never completes.
    */
-  static Future/*<T>*/ any/*<T>*/(Iterable<Future/*<T>*/> futures) {
-    var completer = new Completer/*<T>*/.sync();
-    var onValue = (/*=T*/ value) {
+  static Future<T> any<T>(Iterable<Future<T>> futures) {
+    var completer = new Completer<T>.sync();
+    var onValue = (T value) {
       if (!completer.isCompleted) completer.complete(value);
     };
     var onError = (error, stack) {
       if (!completer.isCompleted) completer.completeError(error, stack);
     };
     for (var future in futures) {
       future.then(onValue, onError: onError);
     }
     return completer.future;
   }
@@ skipping 14 matching lines @@
    */
   static Future forEach(Iterable input, f(element)) {
     Iterator iterator = input.iterator;
     return doWhile(() {
       if (!iterator.moveNext()) return false;
       return new Future.sync(() => f(iterator.current)).then((_) => true);
     });
   }
 
   /**
-   * Perform an async operation repeatedly until it returns `false`.
+   * Performs an async operation repeatedly until it returns `false`.
    *
-   * Runs [f] repeatedly, starting the next iteration only when the [Future]
-   * returned by [f] completes to `true`. Returns a [Future] that completes once
-   * [f] returns `false`.
+   * The function [f] is called repeatedly while it returns either the [bool]
+   * value `true` or a [Future] which completes with the value `true`.
    *
-   * The return values of all [Future]s are discarded. Any errors will cause the
-   * iteration to stop and will be piped through the returned [Future].
+   * If a call to [f] returns `false` or a [Future] that completes to `false`,
+   * iteration ends and the future returned by [doWhile] is completed.
    *
-   * The function [f] may return either a [bool] or a [Future] that completes to
-   * a [bool]. If it returns a non-[Future], iteration continues immediately.
-   * Otherwise it waits for the returned [Future] to complete.
+   * If a future returned by [f] completes with an error, iteration ends and
+   * the future returned by [doWhile] completes with the same error.
+   *
+   * The [f] function must return either a `bool` value or a [Future] completing
+   * with a `bool` value.
    */
   static Future doWhile(f()) {
     _Future doneSignal = new _Future();
     var nextIteration;
     // Bind this callback explicitly so that each iteration isn't bound in the
     // context of all the previous iterations' callbacks.
     nextIteration = Zone.current.bindUnaryCallback((bool keepGoing) {
       if (keepGoing) {
         new Future.sync(f).then(nextIteration,
                                 onError: doneSignal._completeError);
@@ skipping 37 matching lines @@
    * the future returned by `then` will be completed with
    * the same result as the future returned by the callback.
    *
    * If [onError] is not given, and this future completes with an error,
    * the error is forwarded directly to the returned future.
    *
    * In most cases, it is more readable to use [catchError] separately, possibly
    * with a `test` parameter, instead of handling both value and error in a
    * single [then] call.
    */
-  Future/*<S>*/ then/*<S>*/(onValue(T value), { Function onError });
+  Future<S> then<S>(FutureOr<S> onValue(T value), { Function onError });
 
   /**
    * Handles errors emitted by this [Future].
    *
    * This is the asynchronous equivalent of a "catch" block.
    *
    * Returns a new [Future] that will be completed with either the result of
    * this future or the result of calling the `onError` callback.
    *
    * If this future completes with a value,
@@ skipping 42 matching lines @@
    */
   // The `Function` below can stand for several types:
   // - (dynamic) -> T
   // - (dynamic, StackTrace) -> T
   // - (dynamic) -> Future<T>
   // - (dynamic, StackTrace) -> Future<T>
   // Given that there is a `test` function that is usually used to do an
   // `isCheck` we should also expect functions that take a specific argument.
   // Note: making `catchError` return a `Future<T>` in non-strong mode could be
   // a breaking change.
-  Future/*<T>*/ catchError(Function onError,
+  Future<T> catchError(Function onError,
                            {bool test(Object error)});
 
   /**
    * Register 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.
    *
    * This is the asynchronous equivalent of a "finally" block.
    *
@@ skipping 246 matching lines @@
   if (replacement != null) {
     error = _nonNullError(replacement.error);
     stackTrace = replacement.stackTrace;
   }
   result._completeError(error, stackTrace);
 }
 
 /** Helper function that converts `null` to a [NullThrownError]. */
 Object _nonNullError(Object error) =>
   (error != null) ? error : new NullThrownError();