Add an optional start delay to Timer

`Timer()`, `Timer.timeout()`, `Timer.periodic()` and `Timer.reset()`
now take an optional `start_delay` option to make the timer start after
some delay.

This can be useful, for example, if the timer needs to be *aligned* to
a particular time. The alternative to this would be to `sleep()` for the
time needed to align the timer, but if the `sleep()` call gets delayed
because the event loop is busy, then a re-alignment is needed and this
could go on for a while. The only way to guarantee a certain alignment
(with a reasonable precision) is to delay the timer start.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

RELEASE_NOTES.md

@@ -2,15 +2,17 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+The `Timer` now can be started with a delay.
 
 ## Upgrading
 
 <!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+* `Timer()`, `Timer.timeout()`, `Timer.periodic()` and `Timer.reset()` now take an optional `start_delay` option to make the timer start after some delay.
+
+  This can be useful, for example, if the timer needs to be *aligned* to a particular time. The alternative to this would be to `sleep()` for the time needed to align the timer, but if the `sleep()` call gets delayed because the event loop is busy, then a re-alignment is needed and this could go on for a while. The only way to guarantee a certain alignment (with a reasonable precision) is to delay the timer start.
 
 ## Bug Fixes
 

src/frequenz/channels/util/_timer.py

@@ -391,6 +391,7 @@ def __init__(
         /,
         *,
         auto_start: bool = True,
+        start_delay: timedelta = timedelta(0),
         loop: asyncio.AbstractEventLoop | None = None,
     ) -> None:
         """Create an instance.
@@ -408,20 +409,29 @@ def __init__(
                 instance is created. This can only be `True` if there is
                 already a running loop or an explicit `loop` that is running
                 was passed.
+            start_delay: The delay before the timer should start. If `auto_start` is
+                `False`, an exception is raised. This has microseconds resolution,
+                anything smaller than a microsecond means no delay.
             loop: The event loop to use to track time. If `None`,
                 `asyncio.get_running_loop()` will be used.
 
         Raises:
             RuntimeError: if it was called without a loop and there is no
                 running loop.
             ValueError: if `interval` is not positive or is smaller than 1
-                microsecond.
+                microsecond; if `start_delay` is negative or `start_delay` was specified
+                but `auto_start` is `False`.
         """
         if interval < timedelta(microseconds=1):
             raise ValueError(
                 f"The `interval` must be positive and at least 1 microsecond, not {interval}"
             )
 
+        if start_delay > timedelta(0) and auto_start is False:
+            raise ValueError(
+                "`auto_start` must be `True` if a `start_delay` is specified"
+            )
+
         self._interval: int = _to_microseconds(interval)
         """The time to between timer ticks."""
 
@@ -470,7 +480,7 @@ def __init__(
         """
 
         if auto_start:
-            self.reset()
+            self.reset(start_delay=start_delay)
 
     @classmethod
     def timeout(
@@ -479,6 +489,7 @@ def timeout(
         /,
         *,
         auto_start: bool = True,
+        start_delay: timedelta = timedelta(0),
         loop: asyncio.AbstractEventLoop | None = None,
     ) -> Timer:
         """Create a timer useful for tracking timeouts.
@@ -495,6 +506,9 @@ def timeout(
                 instance is created. This can only be `True` if there is
                 already a running loop or an explicit `loop` that is running
                 was passed.
+            start_delay: The delay before the timer should start. If `auto_start` is
+                `False`, an exception is raised. This has microseconds resolution,
+                anything smaller than a microsecond means no delay.
             loop: The event loop to use to track time. If `None`,
                 `asyncio.get_running_loop()` will be used.
 
@@ -505,12 +519,14 @@ def timeout(
             RuntimeError: if it was called without a loop and there is no
                 running loop.
             ValueError: if `interval` is not positive or is smaller than 1
-                microsecond.
+                microsecond; if `start_delay` is negative or `start_delay` was specified
+                but `auto_start` is `False`.
         """
         return Timer(
             delay,
             SkipMissedAndDrift(delay_tolerance=timedelta(0)),
             auto_start=auto_start,
+            start_delay=start_delay,
             loop=loop,
         )
 
@@ -522,6 +538,7 @@ def periodic(
         *,
         skip_missed_ticks: bool = False,
         auto_start: bool = True,
+        start_delay: timedelta = timedelta(0),
         loop: asyncio.AbstractEventLoop | None = None,
     ) -> Timer:
         """Create a periodic timer.
@@ -541,6 +558,9 @@ def periodic(
                 instance is created. This can only be `True` if there is
                 already a running loop or an explicit `loop` that is running
                 was passed.
+            start_delay: The delay before the timer should start. If `auto_start` is
+                `False`, an exception is raised. This has microseconds resolution,
+                anything smaller than a microsecond means no delay.
             loop: The event loop to use to track time. If `None`,
                 `asyncio.get_running_loop()` will be used.
 
@@ -551,7 +571,8 @@ def periodic(
             RuntimeError: if it was called without a loop and there is no
                 running loop.
             ValueError: if `interval` is not positive or is smaller than 1
-                microsecond.
+                microsecond; if `start_delay` is negative or `start_delay` was specified
+                but `auto_start` is `False`.
         """
         missed_tick_policy = (
             SkipMissedAndResync() if skip_missed_ticks else TriggerAllMissed()
@@ -560,6 +581,7 @@ def periodic(
             period,
             missed_tick_policy,
             auto_start=auto_start,
+            start_delay=start_delay,
             loop=loop,
         )
 
@@ -601,19 +623,28 @@ def is_running(self) -> bool:
         """
         return not self._stopped
 
-    def reset(self) -> None:
-        """Reset the timer to start timing from now.
+    def reset(self, *, start_delay: timedelta = timedelta(0)) -> None:
+        """Reset the timer to start timing from now (plus an optional delay).
 
         If the timer was stopped, or not started yet, it will be started.
 
-        This can only be called with a running loop, see the class
-        documentation for more details.
+        This can only be called with a running loop, see the class documentation for
+        more details.
+
+        Args:
+            start_delay: The delay before the timer should start. This has microseconds
+                resolution, anything smaller than a microsecond means no delay.
 
         Raises:
             RuntimeError: if it was called without a running loop.
+            ValueError: if `start_delay` is negative.
         """
+        start_delay_ms = _to_microseconds(start_delay)
+
+        if start_delay_ms < 0:
+            raise ValueError(f"`start_delay` can't be negative, got {start_delay}")
         self._stopped = False
-        self._next_tick_time = self._now() + self._interval
+        self._next_tick_time = self._now() + start_delay_ms + self._interval
         self._current_drift = None
 
     def stop(self) -> None:

tests/utils/test_timer.py

@@ -296,6 +296,7 @@ async def test_timer_contruction_periodic_custom_args() -> None:
         timedelta(seconds=5.0),
         skip_missed_ticks=True,
         auto_start=True,
+        start_delay=timedelta(seconds=1.0),
         loop=None,
     )
     assert timer.interval == timedelta(seconds=5.0)
@@ -304,6 +305,44 @@ async def test_timer_contruction_periodic_custom_args() -> None:
     assert timer.is_running is True
 
 
+async def test_timer_contruction_wrong_args() -> None:
+    """Test the construction of a timeout timer with wrong arguments."""
+    with pytest.raises(
+        ValueError,
+        match="^The `interval` must be positive and at least 1 microsecond, not -1 day, 23:59:55$",
+    ):
+        _ = Timer.periodic(
+            timedelta(seconds=-5.0),
+            skip_missed_ticks=True,
+            auto_start=True,
+            loop=None,
+        )
+
+    with pytest.raises(
+        ValueError,
+        match="^`start_delay` can't be negative, got -1 day, 23:59:59$",
+    ):
+        _ = Timer.periodic(
+            timedelta(seconds=5.0),
+            skip_missed_ticks=True,
+            auto_start=True,
+            start_delay=timedelta(seconds=-1.0),
+            loop=None,
+        )
+
+    with pytest.raises(
+        ValueError,
+        match="^`auto_start` must be `True` if a `start_delay` is specified$",
+    ):
+        _ = Timer.periodic(
+            timedelta(seconds=5.0),
+            skip_missed_ticks=True,
+            auto_start=False,
+            start_delay=timedelta(seconds=1.0),
+            loop=None,
+        )
+
+
 async def test_timer_autostart(
     event_loop: async_solipsism.EventLoop,  # pylint: disable=redefined-outer-name
 ) -> None:
@@ -319,6 +358,28 @@ async def test_timer_autostart(
     assert event_loop.time() == pytest.approx(1.0)
 
 
+async def test_timer_autostart_with_delay(
+    event_loop: async_solipsism.EventLoop,  # pylint: disable=redefined-outer-name
+) -> None:
+    """Test the autostart of a periodic timer with a delay."""
+    timer = Timer(
+        timedelta(seconds=1.0), TriggerAllMissed(), start_delay=timedelta(seconds=0.5)
+    )
+
+    # We sleep some time, less than the interval plus the delay, and then receive from
+    # the timer, since it was automatically started at time 0.5, it should trigger at
+    # time 1.5 without any drift
+    await asyncio.sleep(1.2)
+    drift = await timer.receive()
+    assert drift == pytest.approx(timedelta(seconds=0.0))
+    assert event_loop.time() == pytest.approx(1.5)
+
+    # Still the next tick should be at 2.5 (every second)
+    drift = await timer.receive()
+    assert drift == pytest.approx(timedelta(seconds=0.0))
+    assert event_loop.time() == pytest.approx(2.5)
+
+
 class _StartMethod(enum.Enum):
     RESET = enum.auto()
     RECEIVE = enum.auto()