Update dart:async to match the Dart repo.

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;
 
 /**
  * An object representing a delayed computation.
  *
  * A [Future] is used to represent a potential value, or error,
@@ skipping 77 matching lines @@
  * the `then` call, it would not catch errors from the `bar` call.
  *
  * Futures can have more than one callback-pair registered. Each successor is
  * treated independently and is handled as if it was the only successor.
  *
  * A future may also fail to ever complete. In that case, no callbacks are
  * called.
  */
 abstract class Future<T> {
   // The `_nullFuture` is a completed Future with the value `null`.
-  static final _Future _nullFuture = new _Future.immediate(null);
+  static final _Future _nullFuture = new Future.value(null);
 
   /**
    * Creates a future containing the result of calling [computation]
    * asynchronously with [Timer.run].
    *
    * If the result of executing [computation] throws, the returned future is
    * completed with the error.
    *
    * If the returned value is itself a [Future], completion of
    * the created future will wait until the returned future completes,
    * and will then complete with the same result.
    *
    * If a non-future value is returned, the returned future is completed
    * with that value.
    */
   factory Future(computation()) {
-    _Future result = new _Future<T>();
+    _Future<T> result = new _Future<T>();
     Timer.run(() {
       try {
         result._complete(computation());
       } catch (e, s) {
         _completeWithErrorCallback(result, e, s);
       }
     });
     return result;
   }
 
   /**
    * Creates a future containing the result of calling [computation]
    * asynchronously with [scheduleMicrotask].
    *
    * If executing [computation] throws,
    * the returned future is completed with the thrown error.
    *
    * If calling [computation] returns a [Future], completion of
    * the created future will wait until the returned future completes,
    * and will then complete with the same result.
    *
    * If calling [computation] returns a non-future value,
    * the returned future is completed with that value.
    */
   factory Future.microtask(computation()) {
-    _Future result = new _Future<T>();
+    _Future<T> result = new _Future<T>();
     scheduleMicrotask(() {
       try {
         result._complete(computation());
       } catch (e, s) {
         _completeWithErrorCallback(result, e, s);
       }
     });
     return result;
   }
 
@@ skipping 62 matching lines @@
    * If [computation] is omitted,
    * it will be treated as if [computation] was set to `() => null`,
    * and the future will eventually complete with the `null` value.
    *
    * 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, [T computation()]) {
-    _Future result = new _Future<T>();
+  factory Future.delayed(Duration duration, [computation()]) {
+    _Future<T> result = new _Future<T>();
     new Timer(duration, () {
       try {
         result._complete(computation == null ? null : computation());
       } catch (e, s) {
         _completeWithErrorCallback(result, e, s);
       }
     });
     return result;
   }
 
@@ skipping 25 matching lines @@
     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 value2 in values) {
-            if (value2 != null) {
+          for (var value in values) {
+            if (value != null) {
               // Ensure errors from cleanUp are uncaught.
-              new Future.sync(() { cleanUp(value2); });
+              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 value) {
+      future.then((Object/*=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);
           }
         }
       }, onError: handleError);
     }
     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) {
+      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;
+  }
+
+
+  /**
    * Perform an async operation for each element of the iterable, in turn.
    *
    * Runs [f] for each element in [input] in order, moving to the next element
    * only when the [Future] returned by [f] completes. Returns a [Future] that
    * completes when all elements have been processed.
    *
    * 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 [f] returns a non-[Future], iteration continues immediately. Otherwise
@@ skipping 124 matching lines @@
    *                     if (onError is ZoneBinaryCallback) {
    *                       return onError(e, stackTrace);
    *                     }
    *                     return onError(e);
    *                   }
    *                   throw e;
    *                 });
    *     }
    *
    */
-  Future catchError(Function onError,
-                    {bool test(Object error)});
+  // 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,
+                           {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.
    *
    * The future returned by this call, `f`, will complete the same way
@@ skipping 38 matching lines @@
 
   /**
    * Time-out the future computation after [timeLimit] has passed.
    *
    * Returns a new future that completes with the same value as this future,
    * if this future completes in time.
    *
    * If this future does not complete before `timeLimit` has passed,
    * the [onTimeout] action is executed instead, and its result (whether it
    * returns or throws) is used as the result of the returned future.
+   * The [onTimeout] function must return a [T] or a `Future<T>`.
    *
    * If `onTimeout` is omitted, a timeout will cause the returned future to
    * complete with a [TimeoutException].
    */
-  Future timeout(Duration timeLimit, {onTimeout()});
+  Future<T> timeout(Duration timeLimit, {onTimeout()});
 }
 
 /**
  * Thrown when a scheduled timeout happens while waiting for an async result.
  */
 class TimeoutException implements Exception {
   /** Description of the cause of the timeout. */
   final String message;
   /** The duration that was exceeded. */
   final Duration duration;
@@ skipping 79 matching lines @@
    * Completes the future synchronously.
    *
    * This constructor should be avoided unless the completion of the future is
    * known to be the final result of another asynchronous operation. If in doubt
    * use the default [Completer] constructor.
    *
    * Using an normal, asynchronous, completer will never give the wrong
    * behavior, but using a synchronous completer incorrectly can cause
    * otherwise correct programs to break.
    *
-   * An asynchronous completer is only intended for optimizing event
+   * A synchronous completer is only intended for optimizing event
    * propagation when one asynchronous event immediately triggers another.
    * It should not be used unless the calls to [complete] and [completeError]
    * are guaranteed to occur in places where it won't break `Future` invariants.
    *
    * Completing synchronously means that the completer's future will be
    * completed immediately when calling the [complete] or [completeError]
    * method on a synchronous completer, which also calls any callbacks
    * registered on that future.
    *
    * Completing synchronously must not break the rule that when you add a
@@ skipping 81 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();