boost::capy::task

Lazy coroutine task satisfying IoRunnable.

Synopsis

Declared in <boost/capy/task.hpp>

template<typename T = void>
struct task;

Description

Use task<T> as the return type for coroutines that perform I/O and return a value of type T. The coroutine body does not start executing until the task is awaited, enabling efficient composition without unnecessary eager execution.

The task participates in the I/O awaitable protocol: when awaited, it receives the caller's executor and stop token, propagating them to nested co_await expressions. This enables cancellation and proper completion dispatch across executor boundaries.

Thread Safety

Distinct objects: Safe. Shared objects: Unsafe.

Example

task<int> compute_value()
{
    auto [ec, n] = co_await stream.read_some( buf );
    if( ec )
        co_return 0;
    co_return process( buf, n );
}

task<> run_session( tcp_socket sock )
{
    int result = co_await compute_value();
    // ...
}