boost::capy::IoRunnable

Concept for task types that can be launched from non‐coroutine contexts.

Synopsis

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

template<typename T>
concept IoRunnable = IoAwaitable<T> &&
    requires { typename T::promise_type; } &&
    requires(T& t, T const& ct, typename T::promise_type const& cp, typename T::promise_type& p)
    {
        { ct.handle() } noexcept ‐> std::same_as<std::coroutine_handle<typename T::promise_type>>;
        { cp.exception() } noexcept ‐> std::same_as<std::exception_ptr>;
        { t.release() } noexcept;
        { p.set_continuation(std::coroutine_handle<>{}) } noexcept;
        { p.set_environment(static_cast<io_env const*>(nullptr)) } noexcept;
    } &&
    (std::is_void_v<decltype(std::declval<T&>().await_resume())> ||
     requires(typename T::promise_type& p) {
         p.result();
     });

Description

Extends IoAwaitable with operations needed by launch utilities (run, run_async) to start a task, transfer ownership of the coroutine frame, and retrieve results or exceptions after completion.

Syntactic Requirements

`T` must satisfy IoAwaitable
`T::promise_type` must be a valid type
`t.handle()` returns `std::coroutine_handle<T::promise_type>`, must be `noexcept`
`t.release()` releases ownership, must be `noexcept`
`p.exception()` returns `std::exception_ptr`, must be `noexcept`
`p.result()` returns the task result (required for non‐void tasks)
`p.set_continuation(h)` sets the continuation handle, must be `noexcept`
`p.set_environment(env)` sets the execution environment, must be `noexcept`

Semantic Requirements

The handle operation provides access to the coroutine:

Returns the typed coroutine handle for the task's frame
The task retains ownership; destroying the task destroys the frame

The release operation transfers ownership:

After `release()`, destroying the task does not destroy the frame
The caller becomes responsible for resuming and destroying the frame

The exception operation retrieves failure state:

Returns the exception stored by the promise if the coroutine completed with an unhandled exception
Returns `nullptr` if no exception was thrown

The result operation retrieves success state (non‐void tasks):

Returns the value passed to `co_return`
Behavior is undefined if called when `exception()` is non‐null

The set_continuation operation establishes the continuation:

Sets the coroutine handle to resume when this task reaches `final_suspend`
Used by launch functions to wire the task back to the trampoline

The set_environment operation establishes the execution environment:

Sets the `io_env` pointer that propagates executor, stop token, and allocator through the coroutine chain
The pointed‐to `io_env` must outlive the coroutine

Conforming Signatures

class T
{
public:
    struct promise_type
    {
        std::exception_ptr exception() noexcept;
        R result();  // non-void tasks only
        void set_continuation(std::coroutine_handle<>) noexcept;
        void set_environment(io_env const*) noexcept;
    };

    std::coroutine_handle<promise_type> handle() const noexcept;
    void release() noexcept;
};

Template Parameters

Name	Description
T	The task type.