boost::capy::strand

Provides serialized coroutine execution for any executor type.

Synopsis

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

template<typename Executor>
class strand;

Description

A strand wraps an inner executor and ensures that coroutines dispatched through it never run concurrently. At most one coroutine executes at a time within a strand, even when the underlying executor runs on multiple threads.

Strands are lightweight handles that can be copied freely. Copies share the same internal serialization state, so coroutines dispatched through any copy are serialized with respect to all other copies.

Invariant

Coroutines resumed through a strand shall not run concurrently.

Implementation

The strand uses a service‐based architecture with a fixed pool of 211 implementation objects. New strands hash to select an impl from the pool. Strands that hash to the same index share serialization, which is harmless (just extra serialization) and rare with 211 buckets.

Executor Concept

This class satisfies the Executor concept, providing: ‐ context() ‐ Returns the underlying execution context ‐ on_work_started() / on_work_finished() ‐ Work tracking ‐ dispatch(h) ‐ May run immediately if strand is idle ‐ post(h) ‐ Always queues for later execution

Thread Safety

Distinct objects: Safe. Shared objects: Safe.

Example

thread_pool pool(4);
auto strand = make_strand(pool.get_executor());

// These coroutines will never run concurrently
strand.post(coro1);
strand.post(coro2);
strand.post(coro3);