pw_async: Remove Dispatcher::Run*() methods

Remove Dispatcher::Run*() methods, leaving them in BasicDispatcher
and FakeDispatcher, for the following reasons:
- Run() has already been moved to BasicDisatcher
- It is less important for the Run*() API to be portable. Most portable
libraries only need the Dispatcher::Post*() methods.
- It is unlikely for the Run*() methods to all be supported by all
backends.

Remove Dispatcher::RequestStop(), leaving the method in BasicDispatcher
and FakeDispatcher, for the same reasons listed above for the Run*()
methods.

Add BasicDispatcher Doxygen to pw_async_basic docs.

Change-Id: I7cbcaa9724e74ba9067cfc70da63c25d7033276d
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/133952
Reviewed-by: Erik Gilling <konkers@google.com>
Commit-Queue: Ben Lawson <benlawson@google.com>
Reviewed-by: Keir Mierle <keir@google.com>

3 files changed, 36 insertions, 13 deletions

diff --git a/pw_async_basic/dispatcher_test.cc b/pw_async_basic/dispatcher_test.cc
index 77bfa025c..3f72bbb4f 100644
--- a/pw_async_basic/dispatcher_test.cc
+++ b/pw_async_basic/dispatcher_test.cc
@@ -115,7 +115,7 @@ TEST(DispatcherBasic, RequestStopInsideTask) {
   Task stop_task([&count]([[maybe_unused]] Context& c, Status status) {
     ASSERT_OK(status);
     ++count;
-    c.dispatcher->RequestStop();
+    static_cast<BasicDispatcher*>(c.dispatcher)->RequestStop();
   });
   dispatcher.Post(stop_task);
 
diff --git a/pw_async_basic/docs.rst b/pw_async_basic/docs.rst
index eed19c9a9..0363a2683 100644
--- a/pw_async_basic/docs.rst
+++ b/pw_async_basic/docs.rst
@@ -7,9 +7,15 @@ pw_async_basic
 This module includes basic implementations of pw_async's Dispatcher and
 FakeDispatcher.
 
-Usage
-=====
+---
+API
+---
+.. doxygenclass:: pw::async::BasicDispatcher
+   :members:
 
+-----
+Usage
+-----
 First, set the following GN variables:
 
 .. code-block::
@@ -48,8 +54,7 @@ Next, construct and use a ``BasicDispatcher``.
     return 0;
   }
 
-
+-----------
 Size Report
-===========
-
+-----------
 .. include:: docs_size_report
diff --git a/pw_async_basic/public/pw_async_basic/dispatcher.h b/pw_async_basic/public/pw_async_basic/dispatcher.h
index 2a198bd89..7050d6622 100644
--- a/pw_async_basic/public/pw_async_basic/dispatcher.h
+++ b/pw_async_basic/public/pw_async_basic/dispatcher.h
@@ -22,13 +22,37 @@
 
 namespace pw::async {
 
+/// BasicDispatcher is a generic implementation of Dispatcher.
 class BasicDispatcher final : public Dispatcher, public thread::ThreadCore {
  public:
   explicit BasicDispatcher() = default;
   ~BasicDispatcher() override;
 
+  /// Execute all runnable tasks and return without waiting.
+  void RunUntilIdle();
+
+  /// Run the dispatcher until Now() has reached `end_time`, executing all tasks
+  /// that come due before then.
+  void RunUntil(chrono::SystemClock::time_point end_time);
+
+  /// Run the dispatcher until `duration` has elapsed, executing all tasks that
+  /// come due in that period.
+  void RunFor(chrono::SystemClock::duration duration);
+
+  /// Stop processing tasks. If the dispatcher is serving a task loop, break out
+  /// of the loop, dequeue all waiting tasks, and call their TaskFunctions with
+  /// a PW_STATUS_CANCELLED status. If no task loop is being served, execute the
+  /// dequeueing procedure the next time the Dispatcher is run.
+  void RequestStop() PW_LOCKS_EXCLUDED(lock_);
+
+  // ThreadCore overrides:
+
+  /// Run the dispatcher until RequestStop() is called. Overrides
+  /// ThreadCore::Run() so that BasicDispatcher is compatible with
+  /// pw::thread::Thread.
+  void Run() override PW_LOCKS_EXCLUDED(lock_);
+
   // Dispatcher overrides:
-  void RequestStop() override PW_LOCKS_EXCLUDED(lock_);
   void Post(Task& task) override;
   void PostAfter(Task& task, chrono::SystemClock::duration delay) override;
   void PostAt(Task& task, chrono::SystemClock::time_point time) override;
@@ -38,18 +62,12 @@ class BasicDispatcher final : public Dispatcher, public thread::ThreadCore {
                       chrono::SystemClock::duration interval,
                       chrono::SystemClock::time_point start_time) override;
   bool Cancel(Task& task) override PW_LOCKS_EXCLUDED(lock_);
-  void RunUntilIdle() override;
-  void RunUntil(chrono::SystemClock::time_point end_time) override;
-  void RunFor(chrono::SystemClock::duration duration) override;
 
   // VirtualSystemClock overrides:
   chrono::SystemClock::time_point now() override {
     return chrono::SystemClock::now();
   }
 
-  // ThreadCore overrides:
-  void Run() override PW_LOCKS_EXCLUDED(lock_);
-
  private:
   // Insert |task| into task_queue_ maintaining its min-heap property, keyed by
   // |time_due|.