boost::capy::Executor

Requires a copyable type to dispatch or post continuations to its context.

Synopsis

template<class E>
concept Executor = std::is_nothrow_copy_constructible_v<E> &&
    std::is_nothrow_move_constructible_v<E> &&
    requires(E& e, E const& ce, E const& ce2, continuation c) {
        { ce == ce2 } noexcept ‐> std::convertible_to<bool>;
        { ce.context() } noexcept;
        requires std::is_lvalue_reference_v<decltype(ce.context())> &&
            std::derived_from<
                std::remove_reference_t<decltype(ce.context())>,
                execution_context>;
        { ce.on_work_started() } noexcept;
        { ce.on_work_finished() } noexcept;

        { ce.dispatch(c) } ‐> std::same_as<std::coroutine_handle<>>;
        { ce.post(c) };
    };

Description

An executor embodies a set of rules for determining how and where coroutines are executed. It provides operations to submit work and to track outstanding work for graceful shutdown.

Ordinary users writing coroutine tasks do not interact with dispatch and post directly. These operations are used by authors of coroutine machinery ‐‐ promise_type implementations, awaitables, await_transform. That code implements asynchronous algorithms such as when_all, when_any, async_mutex, channels, and similar primitives.

Syntactic Requirements

  • E must be nothrow copy and move constructible.

  • ce == ce2 must return a type convertible to bool, noexcept.

  • ce.context() must return an lvalue reference to a type derived from execution_context, noexcept.

  • ce.on_work_started() must be valid and noexcept.

  • ce.on_work_finished() must be valid and noexcept.

  • ce.dispatch(c) must return std::coroutine_handle<>.

  • ce.post(c) must be valid.

Semantic Requirements

The context operation returns the owning context:

  • Returns a reference to the execution context that created this executor.

  • The context outlives all executors created from it.

The on_work_started and on_work_finished operations track work:

  • Calls must be paired; each on_work_started must have a matching on_work_finished.

  • The context uses this count to determine when shutdown is complete.

  • These are not intended for direct use by callers. They are public so that work guards can invoke them. This enables user‐defined guards with additional tracking behaviors, without the library needing to grant friendship to types it cannot anticipate.

The dispatch operation returns a handle for symmetric transfer:

Every coroutine resumption must go through symmetric transfer or the executor's queue. It must never go through an inline resume() or dispatch() that creates a frame below the resumed coroutine.

  • If the executor determines it is safe to resume inline, returns c.h for the caller to use in symmetric transfer. One such case is an executor already on the correct thread.

  • Otherwise, posts the continuation for later execution and returns std::noop_coroutine().

  • The caller must use the returned handle appropriately. Return it from await_suspend for symmetric transfer, or call .resume() if at the event loop pump level.

A conforming implementation might look like:

class E
{
    capy::execution_context& ctx_;
    std::thread::id home_ = std::this_thread::get_id();

public:
    explicit E(capy::execution_context& ctx) noexcept : ctx_(ctx) {}

    capy::execution_context& context() const noexcept { return ctx_; }
    void on_work_started() const noexcept {}
    void on_work_finished() const noexcept {}

    bool operator==(E const& other) const noexcept
    {
        return &ctx_ == &other.ctx_;
    }

    std::coroutine_handle<> dispatch(
        capy::continuation& c ) const
    {
        if( std::this_thread::get_id() == home_ )
            return c.h;            // symmetric transfer
        post( c );
        return std::noop_coroutine();
    }

    void post( capy::continuation& ) const
    {
        // enqueue for later execution on this executor's context
    }
};

static_assert( capy::Executor<E> );

The post operation queues for later execution:

  • Never blocks the caller.

  • The coroutine executes on the executor's associated context.

Continuation Lifetime

Both dispatch and post operate on the caller's continuation object by reference. The continuation must remain at a stable address and must not be moved or destroyed until the executor has dequeued and resumed it. Destroying or moving a continuation while it is linked into an executor's queue is undefined behavior.

When dispatch returns c.h (the inline case), the continuation is not enqueued and may be reused or destroyed immediately. When dispatch falls through to post, the continuation is enqueued and the lifetime requirement applies.

Frame Allocator TLS

The library propagates a frame allocator via thread‐local storage. When a custom executor's event loop calls .resume() to drain its work queue, it must use safe_resume() from <boost/capy/ex/frame_allocator.hpp> instead of calling h.resume() directly. This saves and restores the thread‐local frame allocator around the call, preventing a resumed coroutine from permanently overwriting the caller's value.

Executor Validity

Once ctx.shutdown() has begun, the context runs no more work. dispatch and post remain valid until the context is destroyed, but never run the coroutine they are given: the executor passes the continuation to abandon, either at once or no later than the context's destruction, as a context does with the coroutines it holds. An executor takes a continuation off its queue before it resumes or abandons it. A queued copy keeps the continuation's owner, which abandon needs. An abandon made inside post may unwind the chain before post returns, so it is the executor's last touch of the continuation, and of the executor object itself, which may live in a frame the unwind destroys. A post that throws has neither queued nor abandoned the continuation; the caller still holds it. Copy, comparison, context(), on_work_started, and on_work_finished also remain valid until the context is destroyed. Calling any member after the context is destroyed is undefined behavior.

Throwing post or dispatch

An exception from post or dispatch reaches the caller only where nothing has started yet: run_async rethrows it after destroying the unstarted task. Everywhere else the library calls them where an exception cannot propagate, and std::terminate is called: while a task is suspending, which includes when_all and when_any starting their children and run moving to its executor; when abandon posts an unwind; when a join or a run boundary resumes the coroutine awaiting it; and when async_mutex, async_event or async_waker resumes a waiter, whether from an unlock, a set, a wake, a stop request or its own destruction.

Thread Safety

Distinct objects: Safe. Shared objects: Safe for copy, comparison, and context().

Conforming Signatures

class E
{
public:
    capy::execution_context& context() const noexcept;

    void on_work_started() const noexcept;
    void on_work_finished() const noexcept;

    std::coroutine_handle<> dispatch(
        capy::continuation& c ) const;
    void post( capy::continuation& c ) const;

    bool operator==( E const& ) const noexcept;
};

Template Parameters

Name

Description

E

The executor type.

See Also