Add a ResetTimer class.

lib/src/reset_timer.dart

+// Copyright (c) 2015, 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.
+
+library async.reset_timer;
+
+import 'dart:async';
+
+/// A non-periodic timer that can be reset.

[Lasse Reichstein Nielsen, 2015/10/27 09:45:14]

"reset" isn't a very descriptive word, it doesn't tell me what it means to reset
a timer.
Maybe "restarted" or "reused" is a better description of what it does.
I'd prefer "ReuseTimer" or "ReusableTimer" as the class name as well.

Maybe:
/// A non-periodic timer that can be restarted.
///
/// The timer can be restarted both before and after it has fired.

[nweiz, 2015/10/27 21:08:12]

I chose "reset" because it's already used by a number of core library types,
most notably Stopwatch where it has very similar semantics to this. It seems
really confusing to have some methods named "reset" and some named "restart".
It's a lot like using Map.length rather than e.g. Map.size—"size" is slightly
more appropriate in the abstract, but "length" is better in the context of the
existing libraries.

I'm okay with ReusableTimer, but I do kind of feel like it emphasizes the wrong
thing. For most of the use-cases I have in mind for this, the major reason they
would use this rather than a normal Timer is because they want to reset the
countdown. A lot of the time (e.g. for timeout errors), it will still only fire
once.

[Lasse Reichstein Nielsen, 2015/10/28 09:51:02]

I have no problem with "reset" as the name of the method, but by itself it's not
descriptive enough to say what a "ResetTimer" or "ResettableTimer" does. It's
too generic a name to use as the description of what it does since it's already
used in many settings with different meanings.

That means that the method should be called reset, but the documentation and
class name should be more descriptive, giving the context that explains what
"reset" means in this case.

I'm not sure exactly what the name should be. "ReusableTimer" isn't very good,
for the reasons you state. "RestartableTimer" is better but still doesn't feel
perfect to me. "RepeatTimer" has potential, but may sound too much like a
periodic timer. "ReTimer" is cute, but flawed :)

I think "RestartableTimer" is the best bet so far.

[nweiz, 2015/10/28 21:10:43]

Done.

+class ResetTimer implements Timer {
+  /// The duration of the timer.
+  final Duration _duration;
+
+  /// The callback to call when the timer fires.

[Lasse Reichstein Nielsen, 2015/10/27 09:45:14]

Would it be useful to make the callback settable?

[nweiz, 2015/10/27 21:08:12]

I don't think so; if that's what you want, just hook it up to a completer or
something.

+  final ZoneCallback _callback;
+
+  /// The inner timer.

[Lasse Reichstein Nielsen, 2015/10/27 09:45:14]

Being "inner" doesn't say anything about the role of this timer.
Maybe "The timer for the current, or most recent, countdown".

[nweiz, 2015/10/27 21:08:12]

Done.

+  ///
+  /// This is canceled and re-created every time this is reset.

[Lasse Reichstein Nielsen, 2015/10/27 09:45:14]

Two uses of "this" referring to different things.
Maybe:
  This timer is canceled and overwritten every time the [ReuseTimer] is [reset].

[nweiz, 2015/10/27 21:08:12]

Done.

+  Timer _timer;
+
+  bool get isActive => _timer.isActive;

[Lasse Reichstein Nielsen, 2015/10/27 09:45:14]

Move getter below constructor.

[nweiz, 2015/10/27 21:08:12]

Done.

+
+  /// Creates a new timer.
+  ///
+  /// The [callback] function is invoked after the given [duration]. Unlike a
+  /// normal non-periodic [Timer], [callback] may be called more than once.
+  ResetTimer(this._duration, this._callback) {
+    _timer = new Timer(_duration, _callback);
+  }
+
+  /// Resets the timer so that it starts counting from its original duration again.

[Lasse Reichstein Nielsen, 2015/10/27 09:45:14]

Resets -> restarts.
The "reset" name is fine for the method name, the documentation has to describe
what it means to "reset", so it can't use the same word.

[Lasse Reichstein Nielsen, 2015/10/27 09:45:14]

long line.

so that it starts ... -> and starts counting from the original duration again

[nweiz, 2015/10/27 21:08:12]

Done.

[nweiz, 2015/10/27 21:08:12]

Done.

+  ///
+  /// This resets the timer even if it's already fired or has been canceled.

[Lasse Reichstein Nielsen, 2015/10/27 09:45:14]

resets -> restarts
it's -> it has

[nweiz, 2015/10/27 21:08:12]

Done.

+  void reset() {
+    _timer.cancel();
+    _timer = new Timer(_duration, _callback);
+  }
+
+  void cancel() {
+    _timer.cancel();
+  }
+}