♻️ Add guard to use pointers, add signal-based I/O, and rename listener API (#92)

This commit makes three major changes:

1. **guard class**: Converted from references to pointers with proper
   move semantics—moved-from objects null out both pointers.
2. **I/O state**: Renamed `blocked_by::io` and `blocked_by::external`
   to `blocked_by::signal` to clarify that any external events trigger
   unblocking.
3. **Listener API**: Renamed `unblock_listener` to `context_listener`
   and `on_unblock()` to `set_listener()`, plus added `on_sync_block()`
   callback for sync contention tracking.

The changes improve semantic clarity around blocking states and make the
guard type safely movable with proper cleanup semantics.

Co-authored-by: Malia Labor (@MaliaLabor)

Author: kammce

CMakeLists.txt

@@ -25,7 +25,9 @@ libhal_add_library(async_context
     MODULES
         modules/async_context.cppm
         modules/coroutine.cppm
-        modules/schedulers.cppm)
+        modules/schedulers.cppm
+        modules/sync.cppm
+)
 libhal_apply_compile_options(async_context)
 libhal_install_library(async_context NAMESPACE libhal)
 libhal_add_tests(async_context
@@ -34,9 +36,9 @@ libhal_add_tests(async_context
         basics
         blocked_by
         cancel
-        exclusive_access
+        mutex
         proxy
-        on_unblock
+        context_listener
         simple_scheduler
         clock_adapter
         run_until_done

README.md

@@ -34,7 +34,7 @@ using namespace std::chrono_literals;
 async::future<int> read_sensor(async::context& ctx, std::string_view p_name)
 {
   std::println("['{}': Sensor] Starting read...", p_name);
-  co_await ctx.block_by_io();  // Simulate I/O operation
+  co_await ctx.block_by_signal();  // Simulate I/O operation
   std::println("['{}': Sensor] Read complete: 42", p_name);
   co_return 42;
 }
@@ -57,7 +57,7 @@ async::future<void> write_actuator(async::context& ctx,
                                    int value)
 {
   std::println("['{}': Actuator] Writing {}...", p_name, value);
-  co_await ctx.block_by_io();
+  co_await ctx.block_by_signal();
   std::println("['{}': Actuator] Write complete!", p_name);
 }
 
@@ -84,10 +84,10 @@ async::future<void> io_unblock_driver(async::context& p_ctx,
     if (ctx1.done() && ctx2.done()) {
       co_return;
     }
-    if (ctx1.state() == async::blocked_by::io) {
+    if (ctx1.state() == async::blocked_by::signal) {
       ctx1.unblock();
     }
-    if (ctx2.state() == async::blocked_by::io) {
+    if (ctx2.state() == async::blocked_by::signal) {
       ctx2.unblock();
     }
     co_await 1us;
@@ -410,7 +410,7 @@ async::future<void> io_example(async::context& p_ctx) {
     // Start DMA transaction...
 
     while (!dma_complete) {
-        co_await p_ctx.block_by_io();
+        co_await p_ctx.block_by_signal();
     }
     co_return;
 }
@@ -419,7 +419,7 @@ async::future<void> io_example(async::context& p_ctx) {
 Please note that this coroutine has a loop where it continually reports that
 its blocked by IO. It is important that any coroutine blocking by IO check if
 the IO has completed before proceeding. If not, it must
-`co_await ctx.block_by_io();` at some point to give control back to the resumer.
+`co_await ctx.block_by_signal();` at some point to give control back to the resumer.
 
 ### Composing Coroutines
 

docs/api/async_context.md

@@ -27,29 +27,29 @@ Defined in namespace `async::v0`
 ```{doxygenclass} v0::proxy_context
 ```
 
-## async::exclusive_access
+## async::blocked_by
 
 Defined in namespace `async::v0`
 
 *import async_context;*
 
-```{doxygenclass} v0::exclusive_access
+```{doxygenenum} v0::blocked_by
 ```
 
-## async::blocked_by
+## async::future\<T\>
 
 Defined in namespace `async::v0`
 
 *import async_context;*
 
-```{doxygenenum} v0::blocked_by
+```{doxygenclass} v0::future
 ```
 
-## async::future\<T\>
+## async::mutex
 
 Defined in namespace `async::v0`
 
 *import async_context;*
 
-```{doxygenclass} v0::future
+```{doxygenclass} v0::mutex
 ```

modules/async_context.cppm

@@ -16,3 +16,4 @@ export module async_context;
 
 export import :coroutine;
 export import :schedulers;
+export import :sync;