pw_chrono: Add VirtualClock

This CL introduces an extension to VirtualSystemClock
which is clock-generic and changes the existing VirtualSystemClock into
a specialization of this new, more generic interface.

Change-Id: Ibb03dd9257eeed957bcfe2b93b1a0038870083bd
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/233031
Reviewed-by: Aaron Green <aarongreen@google.com>
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>
Commit-Queue: Taylor Cramer <cramertj@google.com>

Author: cramertj

docs/BUILD.gn

@@ -224,8 +224,10 @@ _doxygen_input_files = [  # keep-sorted: start
   "$dir_pw_channel/public/pw_channel/stream_channel.h",
   "$dir_pw_chre/public/pw_chre/chre.h",
   "$dir_pw_chre/public/pw_chre/host_link.h",
+  "$dir_pw_chrono/public/pw_chrono/simulated_system_clock.h",
   "$dir_pw_chrono/public/pw_chrono/system_clock.h",
   "$dir_pw_chrono/public/pw_chrono/system_timer.h",
+  "$dir_pw_chrono/public/pw_chrono/virtual_clock.h",
   "$dir_pw_clock_tree/public/pw_clock_tree/clock_tree.h",
   "$dir_pw_clock_tree_mcuxpresso/public/pw_clock_tree_mcuxpresso/clock_tree.h",
   "$dir_pw_containers/public/pw_containers/filtered_view.h",

pw_async2/BUILD.bazel

@@ -271,6 +271,7 @@ cc_library(
     includes = ["public"],
     deps = [
         ":dispatcher",
+        "//pw_chrono:virtual_clock",
         "//pw_containers:intrusive_list",
         "//pw_sync:interrupt_spin_lock",
         "//pw_toolchain:no_destructor",

pw_async2/public/pw_async2/simulated_time_provider.h

@@ -61,7 +61,7 @@ class SimulatedTimeProvider final : public TimeProvider<Clock> {
   /// one of `AdvanceTime`, `SetTime`, or `RunExpiredTimers` has been called.
   void RunExpiredTimers() { RunExpired(now()); }
 
-  typename Clock::time_point now() const final {
+  typename Clock::time_point now() final {
     std::lock_guard lock(lock_);
     return now_;
   }

pw_async2/public/pw_async2/time_provider.h

@@ -19,6 +19,7 @@
 #include <mutex>
 
 #include "pw_async2/dispatcher.h"
+#include "pw_chrono/virtual_clock.h"
 #include "pw_containers/intrusive_list.h"
 #include "pw_sync/interrupt_spin_lock.h"
 #include "pw_sync/lock_annotations.h"
@@ -44,9 +45,8 @@ class TimeFuture;
 
 /// A factory for time and timers.
 ///
-/// This provides similar functionality as the `VirtualSystemClock` interface
-/// except it can also create timers, and its template parameter means that it
-/// can be used with non-SystemClock clocks.
+/// This extends the `VirtualClock` interface with the ability to create async
+/// timers.
 ///
 /// `TimeProvider` is designed to be dependency-injection friendly so that
 /// code that uses time and timers is not bound to real wall-clock time.
@@ -57,15 +57,14 @@ class TimeFuture;
 /// Note that `Timer` objects must not outlive the `TimeProvider` from which
 /// they were created.
 template <typename Clock>
-class TimeProvider {
+class TimeProvider : public chrono::VirtualClock<Clock> {
  public:
-  /// Gets the current `time_point` for the provided clock.
-  virtual typename Clock::time_point now() const = 0;
-
-  virtual ~TimeProvider() {
+  ~TimeProvider() override {
     internal::AssertTimeFutureObjectsAllGone(futures_.empty());
   }
 
+  typename Clock::time_point now() override = 0;
+
   /// Queues the `callback` to be invoked after `delay`.
   ///
   /// This method is thread-safe and can be invoked from `callback` but may not

pw_async2/system_time_provider.cc

@@ -29,7 +29,7 @@ class SystemTimeProvider final : public TimeProvider<SystemClock> {
             [this](SystemClock::time_point expired) { RunExpired(expired); }) {}
 
  private:
-  SystemClock::time_point now() const final { return SystemClock::now(); }
+  SystemClock::time_point now() final { return SystemClock::now(); }
 
   void DoInvokeAt(SystemClock::time_point time_point) final {
     timer_.InvokeAt(time_point);

pw_chrono/BUILD.bazel

@@ -33,6 +33,14 @@ cc_library(
     includes = ["public"],
 )
 
+cc_library(
+    name = "virtual_clock",
+    hdrs = [
+        "public/pw_chrono/virtual_clock.h",
+    ],
+    includes = ["public"],
+)
+
 pw_facade(
     name = "system_clock",
     srcs = [
@@ -46,6 +54,7 @@ pw_facade(
     includes = ["public"],
     deps = [
         ":epoch",
+        ":virtual_clock",
         "//pw_preprocessor",
     ],
 )

pw_chrono/BUILD.gn

@@ -30,6 +30,11 @@ pw_source_set("epoch") {
   public_configs = [ ":public_include_path" ]
 }
 
+pw_source_set("virtual_clock") {
+  public = [ "public/pw_chrono/virtual_clock.h" ]
+  public_configs = [ ":public_include_path" ]
+}
+
 pw_facade("system_clock") {
   backend = pw_chrono_SYSTEM_CLOCK_BACKEND
   public_configs = [ ":public_include_path" ]
@@ -39,6 +44,7 @@ pw_facade("system_clock") {
   ]
   public_deps = [
     ":epoch",
+    ":virtual_clock",
     "$dir_pw_preprocessor",
   ]
   sources = [ "system_clock.cc" ]

pw_chrono/CMakeLists.txt

@@ -24,6 +24,13 @@ pw_add_library(pw_chrono.epoch INTERFACE
     public
 )
 
+pw_add_library(pw_chrono.virtual_clock INTERFACE
+  HEADERS
+    public/pw_chrono/virtual_clock.h
+  PUBLIC_INCLUDES
+    public
+)
+
 pw_add_facade(pw_chrono.system_clock STATIC
   BACKEND
     pw_chrono.system_clock_BACKEND
@@ -34,6 +41,7 @@ pw_add_facade(pw_chrono.system_clock STATIC
     public
   PUBLIC_DEPS
     pw_chrono.epoch
+    pw_chrono.virtual_clock
     pw_preprocessor
   SOURCES
     system_clock.cc

pw_chrono/docs.rst

@@ -446,6 +446,27 @@ Example in C++
      }
    }
 
+VirtualClock
+============
+Pigweed also includes a virtual base class for timers,
+:cpp:class:`pw::chrono::VirtualClock`. This class allows for writing
+timing-sensitive code that can be tested using simulated clocks such as
+:cpp:class:`pw::chrono::SimulatedSystemClock`.
+
+Using simulated clocks in tests allow tests to avoid sleeping or timeouts,
+resulting in faster and more reliable tests.
+
+See also :cpp:class:`pw::async2::TimeProvider` for creating testable
+time-sensitive code using asynchronous timers.
+
+.. doxygenclass:: pw::chrono::VirtualClock
+  :members:
+
+.. doxygenclass:: pw::chrono::SimulatedSystemClock
+  :members:
+
+
+
 Protobuf
 ========
 Sometimes it's desirable to communicate high resolution time points and

pw_chrono/public/pw_chrono/system_clock.h

@@ -33,6 +33,8 @@
 #include <chrono>
 #include <ratio>
 
+#include "pw_chrono/virtual_clock.h"
+
 namespace pw::chrono {
 namespace backend {
 
@@ -133,14 +135,21 @@ struct SystemClock {
   }
 };
 
+// NOTE: VirtualClock here is specialized on SystemClock in order to provide
+// the `RealClock` function.
+//
+// SystemClock is defined in this file, so there's no risk of an ODR violation
+// as other libraries are unable to spell VirtualClock<SystemClock> unless
+// they have first included this file.
+
 /// An abstract interface representing a SystemClock.
 ///
 /// This interface allows decoupling code that uses time from the code that
 /// creates a point in time. You can use this to your advantage by injecting
 /// Clocks into interfaces rather than having implementations call
 /// `SystemClock::now()` directly. However, this comes at a cost of a vtable per
 /// implementation and more importantly passing and maintaining references to
-/// the VirtualSystemCLock for all of the users.
+/// the VirtualClock for all of the users.
 ///
 /// The `VirtualSystemClock::RealClock()` function returns a reference to the
 /// real global SystemClock.
@@ -162,17 +171,20 @@ struct SystemClock {
 /// @endcode
 ///
 /// This interface is thread and IRQ safe.
-class VirtualSystemClock {
+template <>
+class VirtualClock<SystemClock> {
  public:
   /// Returns a reference to the real system clock to aid instantiation.
-  static VirtualSystemClock& RealClock();
+  static VirtualClock<SystemClock>& RealClock();
 
-  virtual ~VirtualSystemClock() = default;
+  virtual ~VirtualClock() = default;
 
   /// Returns the current time.
   virtual SystemClock::time_point now() = 0;
 };
 
+using VirtualSystemClock = VirtualClock<SystemClock>;
+
 }  // namespace pw::chrono
 
 // The backend can opt to include an inlined implementation of the following:

pw_chrono/public/pw_chrono/virtual_clock.h

@@ -0,0 +1,37 @@
+// Copyright 2024 The Pigweed Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not
+// use this file except in compliance with the License. You may obtain a copy of
+// the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations under
+// the License.
+#pragma once
+
+namespace pw::chrono {
+
+/// An abstract interface representing a Clock.
+///
+/// This interface allows decoupling code that uses time from the code that
+/// creates a point in time. You can use this to your advantage by injecting
+/// Clocks into interfaces rather than having implementations call
+/// `SystemClock::now()` directly. However, this comes at a cost of a vtable per
+/// implementation and more importantly passing and maintaining references to
+/// the VirtualClock for all of the users.
+///
+/// This interface is thread and IRQ safe.
+template <typename Clock>
+class VirtualClock {
+ public:
+  virtual ~VirtualClock() = default;
+
+  /// Returns the current time.
+  virtual typename Clock::time_point now() = 0;
+};
+
+}  // namespace pw::chrono