pw_async: Add docs for pw_async & pw_async_basic

- Add overview & usage guide to pw_async docs.
- Add overview & usage guided to pw_async_basic docs.
- Create pw_async_basic size report and add to pw_async_basic docs.
- Make pw::async::BasicDispatcher::Run() public (this was necessary for
  the size report).
- Add backends to fake_dispatcher_test's enable_if list (this was
  necessary when working on the size report).

Change-Id: I87f6eeaf42c1392094e4ad11df0a90eeb71c0277
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/130490
Commit-Queue: Ben Lawson <benlawson@google.com>
Reviewed-by: Ali Saeed <saeedali@google.com>
Reviewed-by: Keir Mierle <keir@google.com>

7 files changed, 194 insertions, 4 deletions

diff --git a/pw_async_basic/BUILD.bazel b/pw_async_basic/BUILD.bazel
index a8b8bb170..214299ff6 100644
--- a/pw_async_basic/BUILD.bazel
+++ b/pw_async_basic/BUILD.bazel
@@ -23,5 +23,7 @@ filegroup(
         "public/pw_async_basic/task.h",
         "public_overrides/pw_async_backend/fake_dispatcher.h",
         "public_overrides/pw_async_backend/task.h",
+        "size_report/post_1_task.cc",
+        "size_report/task.cc",
     ],
 )
diff --git a/pw_async_basic/BUILD.gn b/pw_async_basic/BUILD.gn
index 4e910d174..e228eddef 100644
--- a/pw_async_basic/BUILD.gn
+++ b/pw_async_basic/BUILD.gn
@@ -16,9 +16,11 @@ import("//build_overrides/pigweed.gni")
 
 import("$dir_pw_async/async.gni")
 import("$dir_pw_async/fake_dispatcher_test.gni")
+import("$dir_pw_bloat/bloat.gni")
 import("$dir_pw_build/target_types.gni")
 import("$dir_pw_chrono/backend.gni")
 import("$dir_pw_docgen/docs.gni")
+import("$dir_pw_sync/backend.gni")
 import("$dir_pw_thread/backend.gni")
 import("$dir_pw_unit_test/test.gni")
 
@@ -31,6 +33,7 @@ config("backend_config") {
   visibility = [ ":*" ]
 }
 
+# Backend for //pw_async:task
 pw_source_set("task") {
   public_configs = [
     ":public_include_path",
@@ -48,9 +51,11 @@ pw_source_set("task") {
   visibility = [
                  ":*",
                  "$dir_pw_async:*",
+                 "size_report:*",
                ] + pw_async_EXPERIMENTAL_MODULE_VISIBILITY
 }
 
+# Backend for //pw_async:fake_dispatcher
 pw_source_set("fake_dispatcher") {
   public_configs = [
     ":public_include_path",
@@ -86,10 +91,13 @@ pw_source_set("dispatcher") {
     "$dir_pw_containers:intrusive_list",
     "$dir_pw_sync:interrupt_spin_lock",
     "$dir_pw_sync:timed_thread_notification",
-    "$dir_pw_thread:thread",
+    "$dir_pw_thread:thread_core",
     dir_pw_log,
   ]
-  visibility = [ ":*" ] + pw_async_EXPERIMENTAL_MODULE_VISIBILITY
+  visibility = [
+                 ":*",
+                 "size_report:*",
+               ] + pw_async_EXPERIMENTAL_MODULE_VISIBILITY
 }
 
 pw_test("dispatcher_test") {
@@ -97,6 +105,7 @@ pw_test("dispatcher_test") {
               pw_thread_THREAD_BACKEND == "$dir_pw_thread_stl:thread"
   public_deps = [
     ":dispatcher",
+    "$dir_pw_thread:thread",
     dir_pw_log,
   ]
   sources = [ "dispatcher_test.cc" ]
@@ -111,4 +120,51 @@ pw_test_group("tests") {
 
 pw_doc_group("docs") {
   sources = [ "docs.rst" ]
+  report_deps = [ ":docs_size_report" ]
+}
+
+pw_size_diff("docs_size_report") {
+  title = "pw_async_basic Docs Size Report"
+  base = "$dir_pw_bloat:bloat_base"
+
+  binaries = []
+
+  if (pw_chrono_SYSTEM_CLOCK_BACKEND != "") {
+    binaries += [
+      {
+        target = "size_report:task"
+        label = "Construct a Task"
+      },
+    ]
+  }
+
+  if (binaries == []) {
+    binaries += [
+      {
+        target = "$dir_pw_bloat:bloat_base"
+        label = "No backend is selected."
+      },
+    ]
+  }
+}
+
+# This size report can't be included in docs because the docs build target uses
+# the target-stm32f429i-disc1 toolchain, which does not support timed thread
+# notifications (mutex & condition_variable headers are not available).
+pw_size_diff("size_report") {
+  title = "pw_async_basic Size Report"
+  base = "$dir_pw_bloat:bloat_base"
+
+  binaries = []
+
+  if (pw_chrono_SYSTEM_CLOCK_BACKEND != "" &&
+      pw_sync_THREAD_NOTIFICATION_BACKEND != "" &&
+      pw_sync_TIMED_THREAD_NOTIFICATION_BACKEND != "") {
+    binaries += [
+      {
+        target = "size_report:post_1_task"
+        label = "Post 1 Task to BasicDispatcher"
+      },
+    ]
+  }
 }
diff --git a/pw_async_basic/docs.rst b/pw_async_basic/docs.rst
index d5c74e08e..fcf26a9ce 100644
--- a/pw_async_basic/docs.rst
+++ b/pw_async_basic/docs.rst
@@ -4,4 +4,52 @@
 pw_async_basic
 ================
 
-The default backend for pw_async.
+This module includes basic implementations of pw_async's Dispatcher and
+FakeDispatcher.
+
+Usage
+=====
+
+First, set the following GN variables:
+
+.. code-block::
+
+  pw_async_TASK_BACKEND="$dir_pw_async_basic:task"
+  pw_async_FAKE_DISPATCHER_BACKEND="$dir_pw_async_basic:fake_dispatcher"
+
+
+Next, create a target that depends on ``//pw_async_basic:dispatcher``:
+
+.. code-block::
+
+  pw_executable("hello_world") {
+    sources = [ "hello_world.cc" ]
+    deps = [
+      "//pw_async_basic:dispatcher",
+    ]
+  }
+
+Next, construct and use a ``BasicDispatcher``.
+
+.. code-block:: cpp
+
+  #include "pw_async_basic/dispatcher.h"
+
+  void DelayedPrint(pw::async::Dispatcher& dispatcher) {
+    dispatcher.PostDelayedTask([](auto&){
+       printf("hello world\n");
+    }, 5s);
+  }
+
+  int main() {
+    pw::async::BasicDispatcher dispatcher;
+    DelayedPrint(dispatcher);
+    dispatcher.RunFor(10s);
+    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 d57f3e488..2e31cde3c 100644
--- a/pw_async_basic/public/pw_async_basic/dispatcher.h
+++ b/pw_async_basic/public/pw_async_basic/dispatcher.h
@@ -50,9 +50,10 @@ class BasicDispatcher final : public Dispatcher, public thread::ThreadCore {
     return chrono::SystemClock::now();
   }
 
- private:
+  // ThreadCore overrides:
   void Run() override PW_LOCKS_EXCLUDED(lock_);
 
+ private:
   // Insert |task| into task_queue_ maintaining its min-heap property, keyed by
   // |time_due|. Must be holding lock_ when calling this function.
   void PostTaskInternal(backend::NativeTask& task,
diff --git a/pw_async_basic/size_report/BUILD.gn b/pw_async_basic/size_report/BUILD.gn
new file mode 100644
index 000000000..a40fc6f4d
--- /dev/null
+++ b/pw_async_basic/size_report/BUILD.gn
@@ -0,0 +1,33 @@
+# Copyright 2023 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.
+
+import("//build_overrides/pigweed.gni")
+
+import("$dir_pw_build/target_types.gni")
+
+pw_executable("post_1_task") {
+  sources = [ "post_1_task.cc" ]
+  deps = [
+    "$dir_pw_async_basic:dispatcher",
+    "$dir_pw_bloat:bloat_this_binary",
+  ]
+}
+
+pw_executable("task") {
+  sources = [ "task.cc" ]
+  deps = [
+    "$dir_pw_async_basic:task",
+    "$dir_pw_bloat:bloat_this_binary",
+  ]
+}
diff --git a/pw_async_basic/size_report/post_1_task.cc b/pw_async_basic/size_report/post_1_task.cc
new file mode 100644
index 000000000..f2e4da470
--- /dev/null
+++ b/pw_async_basic/size_report/post_1_task.cc
@@ -0,0 +1,27 @@
+// Copyright 2023 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.
+
+#include "pw_async_basic/dispatcher.h"
+#include "pw_bloat/bloat_this_binary.h"
+
+int main() {
+  pw::bloat::BloatThisBinary();
+
+  pw::async::BasicDispatcher dispatcher;
+  pw::async::Task task(
+      [](pw::async::Context& /*ctx*/) { printf("hello world\n"); });
+  dispatcher.PostTask(task);
+  dispatcher.Run();
+  return 0;
+}
diff --git a/pw_async_basic/size_report/task.cc b/pw_async_basic/size_report/task.cc
new file mode 100644
index 000000000..d149346fe
--- /dev/null
+++ b/pw_async_basic/size_report/task.cc
@@ -0,0 +1,23 @@
+// Copyright 2023 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.
+
+#include "pw_async/task.h"
+
+#include "pw_bloat/bloat_this_binary.h"
+
+int main() {
+  pw::bloat::BloatThisBinary();
+  pw::async::Task task([](pw::async::Context& /*ctx*/) {});
+  return 0;
+}