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..328679119871909f1fb5da282c391521c96406c8 100644
--- a/sdk/lib/async/timer.dart
+++ b/sdk/lib/async/timer.dart
@@ -6,16 +6,53 @@ part of dart.async;
 
 abstract class Timer {
   /**
-   * Creates a new timer. The [callback] callback is invoked after
-   * [milliseconds] milliseconds.
+   * Runs the given [callback] asynchronously as soon as possible.
+   *
+   * Returns a [Timer] that can be cancelled if the callback is not necessary
+   * anymore.
    */
-  external factory Timer(int milliseconds, void callback(Timer timer));
+  static Timer run(void callback()) {

[Lasse Reichstein Nielsen, 2013/02/11 13:01:21]

Static methods below constructors.

[floitsch, 2013/02/11 19:21:32]

Done.

+    return new Timer(const Duration(), callback);
+  }
 
   /**
-   * Creates a new repeating timer. The [callback] is invoked every
-   * [milliseconds] millisecond until cancelled.
+   * 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.repeating(int milliseconds,
+  // TODO(floitsch): add types.
+  external factory Timer(var duration, Function callback);
+
+  /**
+   * 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(var duration,
                                    void callback(Timer timer));
 
   /**