boost::capy::async_waker

A single‐slot waker that hands one wakeup to a waiting coroutine.

Synopsis

class async_waker;

Description

This is the escape hatch for timing and other external events: the user provides the thread and the clock, capy provides the suspension point. One coroutine suspends in wait(); any thread wakes it with wake().

A wakeup with no waiter present is latched as a single pending token, and the next wait() consumes it immediately. This makes the wake‐before‐wait race benign without any lock protocol. Multiple wakes collapse into one token.

Cancellation

If the environment's stop token is triggered while suspended, the wait completes with error::canceled. A wake that loses the race against cancellation is latched for the next wait() rather than dropped.

Zero Allocation

No heap allocation occurs for wait or wake operations.

Thread Safety

Distinct objects: Safe. Shared objects: wake() may be called from any thread. wait() must only be awaited by one coroutine at a time. The executor must never run the coroutine's continuations concurrently: use a single‐threaded executor, or a strand over a multi‐threaded one. That is the same threading model as async_event and async_mutex. Awaiting wait() directly on a multi‐threaded executor is undefined.

This type is non‐copyable and non‐movable because a suspended waiter holds a pointer into the object.

Example

void waker_example()
{
    capy::async_waker waker;

    // user-provided timing thread
    std::thread th([&waker] {
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
        waker.wake();
    });

    auto waiter = [&waker]() -> capy::task<> {
        auto [ec] = co_await waker.wait();
        // resumed on the executor after ~100ms
    };

    // ... run waiter() on an executor and let the pool drain

    th.join();  // waker.wake() has run; safe to destroy waker now
}

Types

Name

Description

wait_awaiter

Suspends the caller until wake() runs, or resumes it with error::canceled on a stop request.

Member Functions

Name

Description

async_waker [constructor]

Constructors

~async_waker [destructor]

Destroy the waker, canceling a coroutine still waiting.

operator=

Assignment operators

wait

Asynchronously wait until woken.

wake

Wake the waiter, or latch the wakeup if none waits.

Created with MrDocs