Add run_until_done

Author: kammce

CMakeLists.txt

@@ -21,7 +21,10 @@ project(async_context LANGUAGES CXX)
 find_package(LibhalCMakeUtil REQUIRED)
 
 libhal_project_init()
-libhal_add_library(async_context MODULES modules/async_context.cppm)
+libhal_add_library(async_context
+    MODULES
+        modules/async_context.cppm
+        modules/schedulers.cppm)
 libhal_apply_compile_options(async_context)
 libhal_install_library(async_context NAMESPACE libhal)
 libhal_add_tests(async_context
@@ -35,6 +38,8 @@ libhal_add_tests(async_context
         basics_dep_inject
         on_unblock
         simple_scheduler
+        clock_adapter
+        run_until_done
 
     MODULES
         tests/util.cppm

README.md

@@ -22,14 +22,12 @@ performance.
 > 1.0.0 release.
 
 ```C++
-#include <cassert>
-
 #include <chrono>
-#include <coroutine>
 #include <print>
 #include <thread>
 
 import async_context;
+import async_context.schedulers;
 
 using namespace std::chrono_literals;
 
@@ -77,38 +75,45 @@ async::future<void> sensor_pipeline(async::context& ctx,
   std::println("Pipeline '{}' complete!\n", p_name);
 }
 
+// Unblocks any I/O-blocked context in ctx1 or ctx2 (simulates hardware
+// callbacks completing). Runs as a third coroutine alongside the pipelines.
+async::future<void> io_unblock_driver(async::context& p_ctx,
+                                      async::context& ctx1,
+                                      async::context& ctx2)
+{
+  while (true) {
+    if (ctx1.done() && ctx2.done()) {
+      co_return;
+    }
+    if (ctx1.state() == async::blocked_by::io) {
+      ctx1.unblock();
+    }
+    if (ctx2.state() == async::blocked_by::io) {
+      ctx2.unblock();
+    }
+    co_await 1us;
+  }
+}
+
 int main()
 {
-  // Create context and add them to the scheduler
-  basic_context<8192> ctx1(scheduler);
-  basic_context<8192> ctx2(scheduler);
+  async::inplace_context<512> ctx1;
+  async::inplace_context<512> ctx2;
+  async::inplace_context<512> driver_ctx;
 
-  // Run two independent pipelines concurrently
+  // Start the two pipelines and the I/O unblock driver
   auto pipeline1 = sensor_pipeline(ctx1, "🌟 System 1");
   auto pipeline2 = sensor_pipeline(ctx2, "🔥 System 2");
+  auto driver    = io_unblock_driver(driver_ctx, ctx1, ctx2);
 
-  // Round robin between each context
-  while (true) {
-   bool all_done = true;
-   for (auto& ctx : std::to_array({&ctx1, &ctx2}) {
-     if (not ctx->done()) {
-       all_done = false;
-       if (ctx->state() == async::blocked_by::nothing) {
-         ctx->resume();
-       }
-       if (ctx->state() == async::blocked_by::time) {
-         std::this_thread::sleep(ctx.pending_delay());
-         ctx.unblock();
-       }
-     }
-   }
-   if (all_done) {
-     break;
-   }
-  }
-
-  assert(pipeline1.done());
-  assert(pipeline2.done());
+  // Drive all three contexts to completion.
+  // run_until_done sleeps until the nearest time deadline when all contexts
+  // are blocked, and wakes immediately when any context becomes ready.
+  async::chrono_clock_adapter<std::chrono::steady_clock> clk;
+  async::run_until_done(
+    clk,
+    [](auto p_wake_time) { std::this_thread::sleep_until(p_wake_time); },
+    ctx1, ctx2, driver_ctx);
 
   std::println("Both pipelines completed successfully!");
   return 0;
@@ -286,6 +291,90 @@ The state of this can be found from the `async::context::state()`. All states
 besides time are safe to resume at any point. If a context has been blocked by
 time, then it must defer calling resume until that time has elapsed.
 
+## Schedulers
+
+You can import the schedulers by importing `async_context.schedulers`. Importing
+`async_context.schedulers` also transitively imports `async_context`.
+
+### `async::clock` (concept)
+
+An instance-based clock concept. Unlike `std::chrono` clocks which require a
+static `now()`, `async::clock` requires an instance method so hardware clocks
+can be injected as runtime objects. A conforming type must provide:
+
+- `time_point` — the type returned by `now()`
+- `duration` — the difference type of two `time_point`s
+- `now() const` — returns the current `time_point`
+- `time_point` arithmetic: subtraction yields `duration`, addition of
+  `duration` yields `time_point`
+- `time_point::max()` — sentinel meaning "never wake"
+
+### `async::chrono_clock_adapter<ChronoClock>`
+
+A zero-size adapter that wraps any `std::chrono`-conforming clock (with a
+static `now()`) into an `async::clock` (with an instance `now()`). Because it
+holds no state, it is always optimized away entirely by the compiler.
+
+```cpp
+async::chrono_clock_adapter<std::chrono::steady_clock> clk;
+static_assert(async::clock<decltype(clk)>);
+
+auto now = clk.now(); // forwards to std::chrono::steady_clock::now()
+```
+
+Use this on hosted platforms. On bare-metal, implement `async::clock` directly
+against your hardware timer peripheral.
+
+### `async::run_until_done`
+
+Drives a fixed set of `async::context` objects to completion in a cooperative
+scheduling loop. On each iteration it resumes every context that is ready or
+whose time deadline has elapsed. When all remaining contexts are blocked, it
+calls the user-supplied `p_sleep_until` callable to suspend the CPU until the
+nearest deadline.
+
+```cpp
+// Without interruptible sleep
+async::run_until_done(
+  clk,
+  [](auto p_wake_time) { std::this_thread::sleep_until(p_wake_time); },
+  ctx0, ctx1, ctx2);
+```
+
+An overload accepts an `async::unblock_listener` as a third argument. The
+listener is registered on every context so that an I/O completion or ISR can
+wake `p_sleep_until` early, avoiding unnecessary latency when all contexts are
+time-blocked but an I/O event arrives before the deadline.
+
+```cpp
+async::run_until_done(
+  clk,
+  [](auto p_wake_time) {
+    // sleep until the deadline OR until woken by the listener below
+    platform_sleep_until(p_wake_time);
+  },
+  async::unblock_listener::from([](async::context& p_ctx) noexcept {
+    // called from ISR/thread when any context is unblocked
+    platform_wake_from_sleep();
+  }),
+  ctx0, ctx1, ctx2);
+```
+
+Key properties:
+
+- **Stack-allocated scheduler table** — no heap allocation; all internal
+  bookkeeping lives on the call stack and is destroyed when the function
+  returns, even on exception
+- **Listener lifetime safety** — every context's listener registration is
+  cleared in the destructor of the internal scheduler entry, so no context
+  can hold a dangling pointer after `run_until_done` returns
+- **Time-only sleep** — `p_sleep_until` is only called when all contexts are
+  time-blocked *and* none are immediately ready; it is never called if work
+  remains
+- **Exceptions** — any exception that propagates out of a coroutine is
+  re-thrown from `run_until_done`; all listener registrations are still
+  cleaned up via RAII before the exception escapes
+
 ## Usage
 
 ### Basic Coroutine
@@ -570,4 +659,4 @@ set(BUILD_BENCHMARKS OFF)
 
 Apache License 2.0 - See [LICENSE](LICENSE) for details.
 
-Copyright 2024 - 2025 Khalil Estell and the libhal contributors
+Copyright 2024 - 2026 Khalil Estell and the libhal contributors

cspell.json

@@ -51,7 +51,8 @@
     "doxygenfunction",
     "doxygenenum",
     "alignof",
-    "inplace"
+    "inplace",
+    "interruptible"
   ],
   "ignorePaths": [
     "build/",

modules/async_context.cppm

@@ -1,4 +1,4 @@
-// Copyright 2024 - 2025 Khalil Estell and the libhal contributors
+// Copyright 2024 - 2026 Khalil Estell and the libhal contributors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -333,7 +333,7 @@ public:
       }
 
     private:
-      void on_unblock(async::context const& p_context) noexcept override
+      void on_unblock(async::context& p_context) noexcept override
       {
         handler(p_context);
       }
@@ -362,7 +362,7 @@ private:
    * @note This method MUST be noexcept and ISR-safe. It may be called from
    * any execution context including interrupt handlers.
    */
-  virtual void on_unblock(context const& p_context) noexcept = 0;
+  virtual void on_unblock(context& p_context) noexcept = 0;
 };
 
 /**
@@ -499,8 +499,6 @@ public:
    */
   constexpr void unblock_without_notification() noexcept
   {
-    // We clear this information after the unblock call to allow the unblock
-    // call to inspect the context's current state.
     get_original().m_state = blocked_by::nothing;
     get_original().m_sleep_time = sleep_duration::zero();
     get_original().m_sync_blocker = nullptr;
@@ -526,6 +524,10 @@ public:
     if (get_original().m_listener) {
       get_original().m_listener->on_unblock(*this);
     }
+
+    // We clear this context state information after the unblock listener is
+    // invoked to allow the unblock listener to inspect the context's current
+    // state prior to being unblocked.
     unblock_without_notification();
   }
 
@@ -664,8 +666,11 @@ public:
    */
   void resume()
   {
-    // We cannot resume the a coroutine blocked by time.
-    // Only the scheduler can unblock a context state.
+    // We cannot resume the a coroutine blocked by time. Only the scheduler can
+    // unblock a context state.
+    //
+    // This needs to be here to ensure that sync_wait is possible, otherwise the
+    // blocked_by::time semantic cannot be supported.
     if (state() != blocked_by::time) {
       m_active_handle.resume();
     }
@@ -924,15 +929,16 @@ private:
     return coroutine_frame_stack_address;
   }
 
+  // A concern for this library is how large the context objet is thus the word
+  // sizes for each field is denoted below.
   std::coroutine_handle<> m_active_handle = noop_sentinel;  // word 1
   uptr* m_stack_pointer = nullptr;                          // word 2
   std::span<uptr> m_stack{};                                // word 3-4
   context* m_original = nullptr;                            // word 5
-  // ----------- Only available from the original -----------
-  unblock_listener* m_listener = nullptr;                // word 6
-  sleep_duration m_sleep_time = sleep_duration::zero();  // word 7
-  context* m_sync_blocker = nullptr;                     // word 8
-  blocked_by m_state = blocked_by::nothing;              // word 9: pad 3
+  unblock_listener* m_listener = nullptr;                   // word 6
+  sleep_duration m_sleep_time = sleep_duration::zero();     // word 7
+  context* m_sync_blocker = nullptr;                        // word 8
+  blocked_by m_state = blocked_by::nothing;                 // word 9: pad 3
 };
 
 /**
@@ -1078,8 +1084,8 @@ public:
 
   inplace_context(inplace_context const&) = delete;
   inplace_context& operator=(inplace_context const&) = delete;
-  inplace_context(inplace_context&&) = default;
-  inplace_context& operator=(inplace_context&&) = default;
+  inplace_context(inplace_context&&) = delete;
+  inplace_context& operator=(inplace_context&&) = delete;
 
   ~inplace_context()
   {