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

Each strand allocates a private serialization state. Strands constructed from the same execution context share a small pool of mutexes (193 entries) selected by hash; mutex sharing causes only brief contention on the push/pop critical section, never cross‐strand state sharing. Construction cost: one std::make_shared per strand.

Executor Concept

This class satisfies the Executor concept, providing:

context() ‐ Returns the underlying execution context
on_work_started() / on_work_finished() ‐ Work tracking
dispatch(continuation&) ‐ May run immediately if strand is idle
post(continuation&) ‐ 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 continuations will never run concurrently
continuation c1{h1}, c2{h2}, c3{h3};
strand.post(c1);
strand.post(c2);
strand.post(c3);