Add Future.timeout.

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 obtain a not yet
@@ skipping 390 matching lines @@
    *                 });
    *     }
    */
   Future<T> whenComplete(action());
 
   /**
    * Creates a [Stream] that sends [this]' completion value, data or error, to
    * its subscribers. The stream closes after the completion value.
    */
   Stream<T> asStream();
+
+  /**
+   * 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.
+   *
+   * If `onTimeout` is omitted, a timeout will cause the returned future to
+   * complete with a [TimeoutException].
+   */
+  Future timeout(Duration timeLimit, [void onTimeout()]);
 }
 
 /**
+ * Thrown when a scheduled timeout happens while waiting for an async result.
+ */
+class TimeoutException implements Exception {
+  /** The duration that was exceeded without a result. */
+  final Duration duration;
+
+  TimeoutException(this.duration);
+
+  String toString() => "Timeout after $duration";
+}
+
+/**
  * A way to produce Future objects and to complete them later
  * with a value or error.
  *
  * If you already have a Future, you probably don't need a Completer.
  * Instead, you can usually use [Future.then], which returns a Future:
  *
  *     Future doStuff(){
  *       return someAsyncOperation().then((result) {
  *         // Do something.
  *       });
@@ skipping 110 matching lines @@
    *     theFuture.catchError(thisCompleter.completeError);
    *
    */
   void completeError(Object error, [StackTrace stackTrace]);
 
   /**
    * Whether the future has been completed.
    */
   bool get isCompleted;
 }