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,

[floitsch, 2013/11/27 12:31:16]

New line before?

[Lasse Reichstein Nielsen, 2013/11/27 12:54:20]

Done.

+   * the [onTimeout] action is executed instead, and its result (whether it
+   * returns or thorws) is used as the result of the returned future.

[floitsch, 2013/11/27 12:31:16]

throws

[Lasse Reichstein Nielsen, 2013/11/27 12:54:20]

Done.

+   */
+  Future timeout(Duration timeLimit, onTimeout());

[floitsch, 2013/11/27 12:31:16]

I think onTimeout should be optional.

[Lasse Reichstein Nielsen, 2013/11/27 12:54:20]

Done.

 }
 
 /**
  * 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(){
@@ skipping 113 matching lines @@
    *     theFuture.catchError(thisCompleter.completeError);
    *
    */
   void completeError(Object error, [StackTrace stackTrace]);
 
   /**
    * Whether the future has been completed.
    */
   bool get isCompleted;
 }