boost::capy::IoAwaitable

Concept for awaitables that participate in the I/O protocol.

Synopsis

Declared in <boost/capy/concept/io_awaitable.hpp>

template<typename A>
concept IoAwaitable = requires(
        A a,
        std::coroutine_handle<> h,
        io_env const* env)
    {
        a.await_suspend(h, env);
    };

Description

An awaitable satisfies IoAwaitable if its await_suspend accepts an io_env, enabling scheduler affinity, cancellation, and allocator propagation. This extended signature distinguishes I/O awaitables from standard C++ awaitables that only take a coroutine handle.

Syntactic Requirements

`a.await_suspend(h, env)` must be a valid expression where: ‐ `h` is a `std::coroutine_handle<>` (coroutine handle) ‐ `env` is an `io_env const*`

Semantic Requirements

When await_suspend is called:

The awaitable uses `env‐>executor` to schedule resumption of the coroutine when the operation completes
The awaitable should monitor `env‐>stop_token` and complete early with a cancellation error if stop is requested
The awaitable may use `env‐>allocator` for internal allocations
The awaitable must propagate `env‐>allocator` faithfully to any child coroutines it creates
The awaitable may return `std::noop_coroutine()` to indicate the operation was started asynchronously

Lifetime

The io_env passed to await_suspend is guaranteed by launch functions such as run or run_async to remain valid for the lifetime of the awaitable's async operation. Awaitables that need to retain access to the environment should store it as io_env const*, never as a copy. Copying is unnecessary and wasteful because the referent is guaranteed to outlive the operation.

Conforming Signatures

struct A
{
    bool await_ready() const noexcept;

    auto await_suspend(
        std::coroutine_handle<> h,
        io_env const* env );

    T await_resume();
};

Example

struct my_io_op
{
    io_env const* env_ = nullptr;
    std::coroutine_handle<> cont_;

    auto await_suspend(
        std::coroutine_handle<> h,
        io_env const* env )
    {
        env_ = env;
        cont_ = h;
        // Pass members by value; capturing this
        // risks use-after-free in async callbacks
        start_async(
            env_->stop_token,
            env_->executor,
            cont_ );
        return std::noop_coroutine();
    }

    bool await_ready() const noexcept { return false; }
    void await_resume() {}
};

Template Parameters

Name	Description
A	The awaitable type.