Support variable duration in RestartableTimer

Closes #900

Rename the existing field to `_defaultDuration` for clarity and update
doc comment references to disambiguate against the argument to `reset`.

Author: natebosch

pkgs/async/CHANGELOG.md

@@ -1,6 +1,12 @@
+## 2.14.0-wip
+
+- Add a `Duration` argument to `RestartableTimer.reset` to allow restarting
+  with variable intervals.
+
 ## 2.13.1
 
-- Fix `StreamGroup.broadcast().close()` to properly complete when all streams in the group close without being explicitly removed.
+- Fix `StreamGroup.broadcast().close()` to properly complete when all streams in
+  the group close without being explicitly removed.
 - Run `dart format` with the new style.
 
 ## 2.13.0

pkgs/async/lib/src/restartable_timer.dart

@@ -7,10 +7,10 @@ import 'dart:async';
 /// A non-periodic timer that can be restarted any number of times.
 ///
 /// Once restarted (via [reset]), the timer counts down from its original
-/// duration again.
+/// or a passed duration.
 class RestartableTimer implements Timer {
-  /// The duration of the timer.
-  final Duration _duration;
+  /// The default duration of the timer.
+  final Duration _defaultDuration;
 
   /// The callback to call when the timer fires.
   final ZoneCallback _callback;
@@ -23,21 +23,24 @@ class RestartableTimer implements Timer {
 
   /// 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.
-  RestartableTimer(this._duration, this._callback)
-      : _timer = Timer(_duration, _callback);
+  /// The [_callback] function is invoked after the given [_defaultDuration] by
+  /// default. Unlike a normal non-periodic [Timer], [_callback] may be called
+  /// more than once.
+  RestartableTimer(this._defaultDuration, this._callback)
+    : _timer = Timer(_defaultDuration, _callback);
 
   @override
   bool get isActive => _timer.isActive;
 
-  /// Restarts the timer so that it counts down from its original duration
-  /// again.
+  /// Restarts the timer so that it counts down again.
   ///
   /// This restarts the timer even if it has already fired or has been canceled.
-  void reset() {
+  /// If [duration] is passed it is used for this cycle of the timer but
+  /// does not change the default duration for this timer if future calls to
+  /// `reset` omit the [duration] argument.
+  void reset([Duration? duration]) {
     _timer.cancel();
-    _timer = Timer(_duration, _callback);
+    _timer = Timer(duration ?? _defaultDuration, _callback);
   }
 
   @override

pkgs/async/pubspec.yaml

@@ -1,5 +1,5 @@
 name: async
-version: 2.13.1
+version: 2.14.0-wip
 description: Utility functions and classes related to the 'dart:async' library.
 repository: https://github.com/dart-lang/core/tree/main/pkgs/async
 issue_tracker: https://github.com/dart-lang/core/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Aasync

pkgs/async/test/restartable_timer_test.dart

@@ -106,4 +106,24 @@ void main() {
       async.elapse(const Duration(seconds: 10));
     });
   });
+
+  test('can be reset with a variable duration', () {
+    FakeAsync().run((async) {
+      var fired = 0;
+      var timer = RestartableTimer(const Duration(seconds: 5), () {
+        fired++;
+      });
+
+      timer.reset(const Duration(seconds: 10));
+      async.elapse(const Duration(seconds: 6));
+      expect(fired, equals(0));
+
+      async.elapse(const Duration(seconds: 5));
+      expect(fired, equals(1));
+
+      timer.reset();
+      async.elapse(const Duration(seconds: 5));
+      expect(fired, equals(2));
+    });
+  });
 }