Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)

// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/capy

// Official repository: https://github.com/cppalliance/capy

//

//

#ifndef BOOST_CAPY_EX_STRAND_HPP

#ifndef BOOST_CAPY_EX_STRAND_HPP

#define BOOST_CAPY_EX_STRAND_HPP

#define BOOST_CAPY_EX_STRAND_HPP

#include <boost/capy/detail/config.hpp>

#include <boost/capy/detail/config.hpp>

#include <boost/capy/coro.hpp>

#include <boost/capy/coro.hpp>

#include <boost/capy/ex/detail/strand_service.hpp>

#include <boost/capy/ex/detail/strand_service.hpp>

#include <type_traits>

#include <type_traits>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

//----------------------------------------------------------

//----------------------------------------------------------

/** Provides serialized coroutine execution for any executor type.

/** Provides serialized coroutine execution for any executor type.

    A strand wraps an inner executor and ensures that coroutines

    A strand wraps an inner executor and ensures that coroutines

    dispatched through it never run concurrently. At most one

    dispatched through it never run concurrently. At most one

    coroutine executes at a time within a strand, even when the

    coroutine executes at a time within a strand, even when the

    underlying executor runs on multiple threads.

    underlying executor runs on multiple threads.

    Strands are lightweight handles that can be copied freely.

    Strands are lightweight handles that can be copied freely.

    Copies share the same internal serialization state, so

    Copies share the same internal serialization state, so

    coroutines dispatched through any copy are serialized with

    coroutines dispatched through any copy are serialized with

    respect to all other copies.

    respect to all other copies.

    @par Invariant

    @par Invariant

    Coroutines resumed through a strand shall not run concurrently.

    Coroutines resumed through a strand shall not run concurrently.

    @par Implementation

    @par Implementation

    The strand uses a service-based architecture with a fixed pool

    The strand uses a service-based architecture with a fixed pool

    of 211 implementation objects. New strands hash to select an

    of 211 implementation objects. New strands hash to select an

    impl from the pool. Strands that hash to the same index share

    impl from the pool. Strands that hash to the same index share

    serialization, which is harmless (just extra serialization)

    serialization, which is harmless (just extra serialization)

    and rare with 211 buckets.

    and rare with 211 buckets.

    @par Executor Concept

    @par Executor Concept

    This class satisfies the `Executor` concept, providing:

    This class satisfies the `Executor` concept, providing:

    - `context()` - Returns the underlying execution context

    - `context()` - Returns the underlying execution context

    - `on_work_started()` / `on_work_finished()` - Work tracking

    - `on_work_started()` / `on_work_finished()` - Work tracking

    - `dispatch(h)` - May run immediately if strand is idle

    - `dispatch(h)` - May run immediately if strand is idle

    - `post(h)` - Always queues for later execution

    - `post(h)` - Always queues for later execution

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.

    Distinct objects: Safe.

    Shared objects: Safe.

    Shared objects: Safe.

    @par Example

    @par Example

    @code

    @code

    thread_pool pool(4);

    thread_pool pool(4);

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

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

    // These coroutines will never run concurrently

    // These coroutines will never run concurrently

    strand.post(coro1);

    strand.post(coro1);

    strand.post(coro2);

    strand.post(coro2);

    strand.post(coro3);

    strand.post(coro3);

    @endcode

    @endcode

    @tparam E The type of the underlying executor. Must

    @tparam E The type of the underlying executor. Must

        satisfy the `Executor` concept.

        satisfy the `Executor` concept.

    @see make_strand, Executor

    @see make_strand, Executor

*/

*/

template<typename Ex>

template<typename Ex>

class strand

class strand

{

{

    detail::strand_impl* impl_;

    detail::strand_impl* impl_;

    Ex ex_;

    Ex ex_;

public:

public:

    /** The type of the underlying executor.

    /** The type of the underlying executor.

    */

    */

    using inner_executor_type = Ex;

    using inner_executor_type = Ex;

    /** Construct a strand for the specified executor.

    /** Construct a strand for the specified executor.

        Obtains a strand implementation from the service associated

        Obtains a strand implementation from the service associated

        with the executor's context. The implementation is selected

        with the executor's context. The implementation is selected

        from a fixed pool using a hash function.

        from a fixed pool using a hash function.

        @param ex The inner executor to wrap. Coroutines will

        @param ex The inner executor to wrap. Coroutines will

            ultimately be dispatched through this executor.

            ultimately be dispatched through this executor.

        @note This constructor is disabled if the argument is a

        @note This constructor is disabled if the argument is a

            strand type, to prevent strand-of-strand wrapping.

            strand type, to prevent strand-of-strand wrapping.

    */

    */

    template<typename Ex1,

    template<typename Ex1,

        typename = std::enable_if_t<

        typename = std::enable_if_t<

            !std::is_same_v<std::decay_t<Ex1>, strand> &&

            !std::is_same_v<std::decay_t<Ex1>, strand> &&

            !detail::is_strand<std::decay_t<Ex1>>::value &&

            !detail::is_strand<std::decay_t<Ex1>>::value &&

            std::is_convertible_v<Ex1, Ex>>>

            std::is_convertible_v<Ex1, Ex>>>

    explicit

    explicit

    {

    {

    /** Copy constructor.

    /** Copy constructor.

        Creates a strand that shares serialization state with

        Creates a strand that shares serialization state with

        the original. Coroutines dispatched through either strand

        the original. Coroutines dispatched through either strand

        will be serialized with respect to each other.

        will be serialized with respect to each other.

    */

    */

    /** Move constructor.

    /** Move constructor.

    */

    */

    strand(strand&&) = default;

    strand(strand&&) = default;

    /** Copy assignment operator.

    /** Copy assignment operator.

    */

    */

    strand& operator=(strand const&) = default;

    strand& operator=(strand const&) = default;

    /** Move assignment operator.

    /** Move assignment operator.

    */

    */

    strand& operator=(strand&&) = default;

    strand& operator=(strand&&) = default;

    /** Return the underlying executor.

    /** Return the underlying executor.

        @return A const reference to the inner executor.

        @return A const reference to the inner executor.

    */

    */

    Ex const&

    Ex const&

    {

    {

    }

    }

    /** Return the underlying execution context.

    /** Return the underlying execution context.

        @return A reference to the execution context associated

        @return A reference to the execution context associated

            with the inner executor.

            with the inner executor.

    */

    */

    auto&

    auto&

    {

    {

    }

    }

    /** Notify that work has started.

    /** Notify that work has started.

        Delegates to the inner executor's `on_work_started()`.

        Delegates to the inner executor's `on_work_started()`.

        This is a no-op for most executor types.

        This is a no-op for most executor types.

    */

    */

    void

    void

    {

    {

    /** Notify that work has finished.

    /** Notify that work has finished.

        Delegates to the inner executor's `on_work_finished()`.

        Delegates to the inner executor's `on_work_finished()`.

        This is a no-op for most executor types.

        This is a no-op for most executor types.

    */

    */

    void

    void

    {

    {

    /** Determine whether the strand is running in the current thread.

    /** Determine whether the strand is running in the current thread.

        @return true if the current thread is executing a coroutine

        @return true if the current thread is executing a coroutine

            within this strand's dispatch loop.

            within this strand's dispatch loop.

    */

    */

    bool

    bool

    {

    {

    }

    }

    /** Compare two strands for equality.

    /** Compare two strands for equality.

        Two strands are equal if they share the same internal

        Two strands are equal if they share the same internal

        serialization state. Equal strands serialize coroutines

        serialization state. Equal strands serialize coroutines

        with respect to each other.

        with respect to each other.

        @param other The strand to compare against.

        @param other The strand to compare against.

        @return true if both strands share the same implementation.

        @return true if both strands share the same implementation.

    */

    */

    bool

    bool

    {

    {

    }

    }

    /** Post a coroutine to the strand.

    /** Post a coroutine to the strand.

        The coroutine is always queued for execution, never resumed

        The coroutine is always queued for execution, never resumed

        immediately. When the strand becomes available, queued

        immediately. When the strand becomes available, queued

        coroutines execute in FIFO order on the underlying executor.

        coroutines execute in FIFO order on the underlying executor.

        @par Ordering

        @par Ordering

        Guarantees strict FIFO ordering relative to other post() calls.

        Guarantees strict FIFO ordering relative to other post() calls.

        Use this instead of dispatch() when ordering matters.

        Use this instead of dispatch() when ordering matters.

        @param h The coroutine handle to post.

        @param h The coroutine handle to post.

    */

    */

    void

    void

    {

    {

    /** Dispatch a coroutine through the strand.

    /** Dispatch a coroutine through the strand.

        If the calling thread is already executing within this strand,

        If the calling thread is already executing within this strand,

        the coroutine is resumed immediately by calling `h.resume()`.

        the coroutine is resumed immediately by calling `h.resume()`.

        The call returns when the coroutine suspends or completes.

        The call returns when the coroutine suspends or completes.

        This provides optimal performance but means the coroutine may

        This provides optimal performance but means the coroutine may

        execute before previously queued work.

        execute before previously queued work.

        Otherwise, the coroutine is queued and will execute in FIFO

        Otherwise, the coroutine is queued and will execute in FIFO

        order relative to other queued coroutines.

        order relative to other queued coroutines.

        After this function returns, the state of `h` is unspecified.

        After this function returns, the state of `h` is unspecified.

        The coroutine may have completed, been destroyed, or suspended

        The coroutine may have completed, been destroyed, or suspended

        at a different suspension point. Callers must not assume `h`

        at a different suspension point. Callers must not assume `h`

        remains valid after calling `dispatch`.

        remains valid after calling `dispatch`.

        @par Ordering

        @par Ordering

        Callers requiring strict FIFO ordering should use post()

        Callers requiring strict FIFO ordering should use post()

        instead, which always queues the coroutine.

        instead, which always queues the coroutine.

        @note Because this function may call `h.resume()` before

        @note Because this function may call `h.resume()` before

        returning, it cannot be used to implement symmetric transfer

        returning, it cannot be used to implement symmetric transfer

        from `await_suspend`.

        from `await_suspend`.

        @param h The coroutine handle to dispatch.

        @param h The coroutine handle to dispatch.

    */

    */

    void

    void

    {

    {

};

};

// Deduction guide

// Deduction guide

template<typename Ex>

template<typename Ex>

strand(Ex) -> strand<Ex>;

strand(Ex) -> strand<Ex>;

} // namespace capy

} // namespace capy

} // namespace boost

} // namespace boost

#endif

#endif