Make the timer generic and support periodic timers (#79)

The current timer provided is very convenient to implement timers, but
it's not very helpful to implement a peridic timer that doesn't
accumulate drift.

This PR makes the timer configurable via *missing ticks policies* and
adds 3 policies: `TriggerAllMissing`, `SkipMissingAndResync` and
`SkipMissingAndDrift`.

For convenience, 2 alternative constructors are provided for the most
common cases: `Timer.timeout()` and `Timer.periodic()`. Timeout timers
always drift and periodic timers never.

The new `Timer` also uses the `asyncio` loop monotonic clock, and
returns the `drift` (difference between when the timer should have
triggered and it actually did) instead of a `datetime` with the time of
trigger.

It is also now possible to control when this timer is started, and can
be stopped and reset/restarted at will.

Fixes #78.

Author: llucax

.github/ISSUE_TEMPLATE/bug.yml

@@ -50,7 +50,7 @@ body:
         - Build script, CI, dependencies, etc. (part:tooling)
         - Channels, `Broadcast`, `Bidirectional`, etc. (part:channels)
         - Select (part:select)
-        - Utility receivers, `Merge`, `Timer`, etc. (part:receivers)
+        - Utility receivers, `Merge`, etc. (part:receivers)
     validations:
       required: true
   - type: textarea

RELEASE_NOTES.md

@@ -2,16 +2,41 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release adds support to pass `None` values via channels and revamps the `Timer` class to support custom policies for handling missed ticks and use the loop monotonic clock.
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including if there are any depractions and what they should be replaced with -->
+* `util.Timer` was replaced by a more generic implementation that allows for customizable policies to handle missed ticks.
+
+  If you were using `Timer` to implement timeouts, these two pices of code should be almost equivalent:
+
+  - Old:
+
+    ```python
+    old_timer = Timer(1.0)
+    triggered_datetime = old_timer.receive()
+    ```
+
+  - New:
+
+    ```python
+    new_timer = Timer.timeout(timedelta(seconds=1.0))
+    drift = new_timer.receive()
+    triggered_datetime = datetime.now(timezone.utc) - drift
+    ```
+
+  They are not **exactly** the same because the `triggered_datetime` in the second case will not be exactly when the timer had triggered, but that shouldn't be relevant, the important part is when your code can actually react to the timer trigger and to know how much drift there was to be able to take corrective actions.
+
+  Also the new `Timer` uses the `asyncio` loop monotonic clock and the old one used the wall clock (`datetime.now()`) to track time. This means that when using `async-solipsism` to test, the new `Timer` will always trigger immediately regarless of the state of the wall clock.
+
+  **Note:** Before replacing this code blindly in all uses of `Timer.timeout()`, please consider using the periodic timer constructor `Timer.periodic()` if you need a timer that triggers reliable on a periodic fashion, as the old `Timer` (and `Timer.timeout()`) accumulates drift, which might not be what you want.
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+* `util.Timer` was replaced by a more generic implementation that allows for customizable policies to handle missed ticks.
+
+* Passing `None` values via channels is now supported.
 
 ## Bug Fixes
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+* `util.Select` / `util.Merge` / `util.MergeNamed`: Cancel pending tasks in `__del__` methods only if possible (the loop is not already closed).

noxfile.py

@@ -28,14 +28,30 @@ def formatting(session: nox.Session) -> None:
 @nox.session
 def pylint(session: nox.Session) -> None:
     """Run pylint to do lint checks."""
-    session.install("-e", ".[docs]", "pylint", "pytest", "nox")
+    session.install(
+        "-e",
+        ".[docs]",
+        "pylint",
+        "pytest",
+        "nox",
+        "async-solipsism",
+        "hypothesis",
+    )
     session.run("pylint", *check_dirs, *check_files)
 
 
 @nox.session
 def mypy(session: nox.Session) -> None:
     """Run mypy to check type hints."""
-    session.install("-e", ".[docs]", "pytest", "nox", "mypy")
+    session.install(
+        "-e",
+        ".[docs]",
+        "pytest",
+        "nox",
+        "mypy",
+        "async-solipsism",
+        "hypothesis",
+    )
 
     common_args = [
         "--namespace-packages",
@@ -59,7 +75,7 @@ def mypy(session: nox.Session) -> None:
 @nox.session
 def docstrings(session: nox.Session) -> None:
     """Check docstring tone with pydocstyle and param descriptions with darglint."""
-    session.install("pydocstyle", "darglint", "toml")
+    session.install("pydocstyle", "darglint", "tomli")
 
     session.run("pydocstyle", *check_dirs, *check_files)
 
@@ -72,7 +88,14 @@ def docstrings(session: nox.Session) -> None:
 @nox.session
 def pytest(session: nox.Session) -> None:
     """Run all tests using pytest."""
-    session.install("pytest", "pytest-cov", "pytest-mock", "pytest-asyncio")
+    session.install(
+        "pytest",
+        "pytest-cov",
+        "pytest-mock",
+        "pytest-asyncio",
+        "async-solipsism",
+        "hypothesis",
+    )
     session.install("-e", ".")
     session.run(
         "pytest",

pyproject.toml

@@ -1,8 +1,8 @@
 [build-system]
 requires = [
-    "setuptools >= 65.3.0, < 66",
-    "setuptools_scm[toml] >= 7.0.5, < 8",
-    "wheel"
+  "setuptools >= 65.3.0, < 66",
+  "setuptools_scm[toml] >= 7.0.5, < 8",
+  "wheel",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -12,36 +12,34 @@ name = "frequenz-channels"
 description = "Channel implementations for Python"
 readme = "README.md"
 license = { text = "MIT" }
-keywords = [ "frequenz", "channel" ]
+keywords = ["frequenz", "channel"]
 classifiers = [
-   "Development Status :: 3 - Alpha",
-   "Intended Audience :: Developers",
-   "License :: OSI Approved :: MIT License",
-   "Programming Language :: Python :: 3",
-   "Programming Language :: Python :: 3 :: Only",
-   "Programming Language :: Python :: 3.8",
-   "Programming Language :: Python :: 3.9",
-   "Programming Language :: Python :: 3.10",
-   "Topic :: Software Development :: Libraries",
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Software Development :: Libraries",
 ]
 requires-python = ">= 3.8, < 4"
-dependencies = [
-    "watchfiles >= 0.15.0",
-]
-dynamic = [ "version" ]
+dependencies = ["watchfiles >= 0.15.0"]
+dynamic = ["version"]
 
 [[project.authors]]
-name ="Frequenz Energy-as-a-Service GmbH"
+name = "Frequenz Energy-as-a-Service GmbH"
 email = "[email protected]"
 
 [project.optional-dependencies]
 docs = [
-    "mike >= 1.1.2, < 2",
-    "mkdocs-gen-files >= 0.4.0, < 0.5.0",
-    "mkdocs-literate-nav >= 0.4.0, < 0.5.0",
-    "mkdocs-material >= 8.5.7, < 9",
-    "mkdocs-section-index >= 0.3.4, < 0.4.0",
-    "mkdocstrings[python] >= 0.19.0, < 0.20.0",
+  "mike >= 1.1.2, < 2",
+  "mkdocs-gen-files >= 0.4.0, < 0.5.0",
+  "mkdocs-literate-nav >= 0.4.0, < 0.5.0",
+  "mkdocs-material >= 8.5.7, < 9",
+  "mkdocs-section-index >= 0.3.4, < 0.4.0",
+  "mkdocstrings[python] >= 0.19.0, < 0.20.0",
 ]
 
 [project.urls]
@@ -57,16 +55,16 @@ include-package-data = true
 version_scheme = "post-release"
 
 [tool.pylint.similarities]
-ignore-comments=['yes']
-ignore-docstrings=['yes']
-ignore-imports=['no']
-min-similarity-lines=40
+ignore-comments = ['yes']
+ignore-docstrings = ['yes']
+ignore-imports = ['no']
+min-similarity-lines = 40
 
 [tool.pylint.messages_control]
 # disable wrong-import-order, ungrouped-imports because it conflicts with isort
 disable = ["too-few-public-methods", "wrong-import-order", "ungrouped-imports"]
 [tool.pylint.'DESIGN']
-max-attributes=12
+max-attributes = 12
 
 [tool.isort]
 profile = "black"
@@ -75,4 +73,8 @@ src_paths = ["src", "examples", "tests"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-required_plugins = [ "pytest-asyncio", "pytest-mock" ]
+required_plugins = ["pytest-asyncio", "pytest-mock"]
+
+[[tool.mypy.overrides]]
+module = ["async_solipsism", "async_solipsism.*"]
+ignore_missing_imports = true

src/frequenz/channels/util/__init__.py

@@ -17,25 +17,34 @@
   multiple receivers into a single named stream, allowing to identify the
   origin of each message.
 
+* [Timer][frequenz.channels.util.Timer]:
+  A [receiver][frequenz.channels.Receiver] that ticks at certain intervals.
+
 * [Select][frequenz.channels.util.Select]: A helper to select the next
   available message for each [receiver][frequenz.channels.Receiver] in a group
   of receivers.
-
-* [Timer][frequenz.channels.util.Timer]:
-  A [receiver][frequenz.channels.Receiver] that emits a *now* `timestamp`
-  every `interval` seconds.
 """
 
 from ._file_watcher import FileWatcher
 from ._merge import Merge
 from ._merge_named import MergeNamed
 from ._select import Select
-from ._timer import Timer
+from ._timer import (
+    MissedTickPolicy,
+    SkipMissedAndDrift,
+    SkipMissedAndResync,
+    Timer,
+    TriggerAllMissed,
+)
 
 __all__ = [
     "FileWatcher",
     "Merge",
     "MergeNamed",
-    "Select",
+    "MissedTickPolicy",
     "Timer",
+    "Select",
+    "SkipMissedAndDrift",
+    "SkipMissedAndResync",
+    "TriggerAllMissed",
 ]