Rework Timer interface.

sdk/lib/async/timer.dart

Index: sdk/lib/async/timer.dart
diff --git a/sdk/lib/async/timer.dart b/sdk/lib/async/timer.dart
index e5b0516849ce2c43d6066039c9d50188e322f039..39fe4c2df6202e1500940372e47d2583085f16b8 100644
--- a/sdk/lib/async/timer.dart
+++ b/sdk/lib/async/timer.dart
@@ -6,19 +6,56 @@ part of dart.async;
 
 abstract class Timer {
   /**
-   * Creates a new timer. The [callback] callback is invoked after
-   * [milliseconds] milliseconds.
+   * Creates a new timer.
+   *
+   * The [callback] callback is invoked after the given [duration]
+   * (a [Duration]) has passed. A negative duration is treated similar to
+   * a duration of 0.
+   *
+   * If the [duration] is statically known to be 0, consider using [run].
+   *
+   * Frequently the [duration] is either a constant or computed as in the
+   * following example (taking advantage of the multiplication operator of
+   * the Duration class):
+   *
+   *     const TIMEOUT = const Duration(seconds: 3);
+   *     const ms = const Duration(milliseconds: 1);
+   *
+   *     startTimeout([int milliseconds]) {
+   *       var duration = milliseconds == null ? TIMEOUT : ms * milliseconds;
+   *       return new Timer(duration, handleTimeout);
+   *     }
+   *
+   * *Deprecation warning*: this constructor used to take an [int] (the time
+   * in milliseconds) and a callback with one argument (the timer). This has
+   * changed to a [Duration] and a callback without arguments.
    */
-  external factory Timer(int milliseconds, void callback(Timer timer));
+  // TODO(floitsch): add types.
+  external factory Timer(var duration, Function callback);
 
   /**
-   * Creates a new repeating timer. The [callback] is invoked every
-   * [milliseconds] millisecond until cancelled.
+   * Creates a new repeating timer.
+   *
+   * The [callback] is invoked repeatedly with [duration] intervals until
+   * canceled. A negative duration is treated similar to a duration of 0.
+   *
+   * *Deprecation warning*: this constructor used to take an [int] (the time
+   * in milliseconds). This has changed to a [Duration].
    */
-  external factory Timer.repeating(int milliseconds,
+  external factory Timer.repeating(var duration,
                                    void callback(Timer timer));
 
   /**
+   * Runs the given [callback] asynchronously as soon as possible.
+   *
+   * Returns a [Timer] that can be cancelled if the callback is not necessary
+   * anymore.
+   */
+  static Timer run(void callback()) {
+    return new Timer(const Duration(), callback);
+  }
+
+  /**
    * Cancels the timer.
    */
   void cancel();