boost::capy::work_guard

RAII guard that keeps an executor's context from completing.

Synopsis

Declared in <boost/capy/ex/work_guard.hpp>

template<Executor Ex>
class work_guard;

Description

This class holds "work" on an executor, preventing the associated execution context's run() function from returning due to lack of work. It calls on_work_started() on construction and on_work_finished() on destruction, ensuring proper work tracking.

The guard is useful when you need to keep an execution context running while waiting for external events or when work will be posted later.

RAII Semantics

Construction calls `ex.on_work_started()`.
Destruction calls `ex.on_work_finished()` if `owns_work()`.
Copy construction creates a new work reference (calls `on_work_started()` again).
Move construction transfers ownership without additional calls.

Thread Safety

Distinct objects may be accessed concurrently. Access to a single object requires external synchronization.

Example

io_context ctx;

// Keep context running while we set things up
auto guard = make_work_guard(ctx);

std::thread t([&ctx]{ ctx.run(); });

// ... post work to ctx ...

// Allow context to complete when work is done
guard.reset();

t.join();

The executor is returned by reference, allowing callers to manage the executor's lifetime directly. This is essential in coroutine‐first designs where the executor often outlives individual coroutine frames.