Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.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_ANY_EXECUTOR_HPP

#ifndef BOOST_CAPY_ANY_EXECUTOR_HPP

#define BOOST_CAPY_ANY_EXECUTOR_HPP

#define BOOST_CAPY_ANY_EXECUTOR_HPP

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

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

#include <boost/capy/continuation.hpp>

#include <boost/capy/continuation.hpp>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <memory>

#include <memory>

#include <type_traits>

#include <type_traits>

#include <typeinfo>

#include <typeinfo>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

class execution_context;

class execution_context;

template<typename> class strand;

template<typename> class strand;

namespace detail {

namespace detail {

template<typename T>

template<typename T>

struct is_strand_type : std::false_type {};

struct is_strand_type : std::false_type {};

template<typename E>

template<typename E>

struct is_strand_type<strand<E>> : std::true_type {};

struct is_strand_type<strand<E>> : std::true_type {};

} // detail

} // detail

/** A type-erased wrapper for executor objects.

/** A type-erased wrapper for executor objects.

    This class provides type erasure for any executor type, enabling

    This class provides type erasure for any executor type, enabling

    runtime polymorphism with automatic memory management via shared

    runtime polymorphism with automatic memory management via shared

    ownership. It stores a shared pointer to a polymorphic wrapper,

    ownership. It stores a shared pointer to a polymorphic wrapper,

    allowing executors of different types to be stored uniformly

    allowing executors of different types to be stored uniformly

    while satisfying the full `Executor` concept.

    while satisfying the full `Executor` concept.

    @par Value Semantics

    @par Value Semantics

    This class has value semantics with shared ownership. Copy and

    This class has value semantics with shared ownership. Copy and

    move operations are cheap, simply copying the internal shared

    move operations are cheap, simply copying the internal shared

    pointer. Multiple `any_executor` instances may share the same

    pointer. Multiple `any_executor` instances may share the same

    underlying executor. Move operations do not invalidate the

    underlying executor. Move operations do not invalidate the

    source; there is no moved-from state.

    source; there is no moved-from state.

    @par Default State

    @par Default State

    A default-constructed `any_executor` holds no executor. Calling

    A default-constructed `any_executor` holds no executor. Calling

    executor operations on a default-constructed instance results

    executor operations on a default-constructed instance results

    in undefined behavior. Use `operator bool()` to check validity.

    in undefined behavior. Use `operator bool()` to check validity.

    @par Thread Safety

    @par Thread Safety

    The `any_executor` itself is thread-safe for concurrent reads.

    The `any_executor` itself is thread-safe for concurrent reads.

    Concurrent modification requires external synchronization.

    Concurrent modification requires external synchronization.

    Executor operations are safe to call concurrently if the

    Executor operations are safe to call concurrently if the

    underlying executor supports it.

    underlying executor supports it.

    @par Executor Concept

    @par Executor Concept

    This class satisfies the `Executor` concept, making it usable

    This class satisfies the `Executor` concept, making it usable

    anywhere a concrete executor is expected.

    anywhere a concrete executor is expected.

    @par Example

    @par Example

    @code

    @code

    any_executor exec = ctx.get_executor();

    any_executor exec = ctx.get_executor();

    if(exec)

    if(exec)

    {

    {

        auto& context = exec.context();

        auto& context = exec.context();

        exec.post(my_coroutine);

        exec.post(my_coroutine);

    }

    }

    @endcode

    @endcode

    @see executor_ref, Executor

    @see executor_ref, Executor

*/

*/

class any_executor

class any_executor

{

{

    struct impl_base;

    struct impl_base;

    std::shared_ptr<impl_base> p_;

    std::shared_ptr<impl_base> p_;

    struct impl_base

    struct impl_base

    {

    {

        virtual execution_context& context() const noexcept = 0;

        virtual execution_context& context() const noexcept = 0;

        virtual void on_work_started() const noexcept = 0;

        virtual void on_work_started() const noexcept = 0;

        virtual void on_work_finished() const noexcept = 0;

        virtual void on_work_finished() const noexcept = 0;

        virtual std::coroutine_handle<> dispatch(continuation&) const = 0;

        virtual std::coroutine_handle<> dispatch(continuation&) const = 0;

        virtual void post(continuation&) const = 0;

        virtual void post(continuation&) const = 0;

        virtual bool equals(impl_base const*) const noexcept = 0;

        virtual bool equals(impl_base const*) const noexcept = 0;

        virtual std::type_info const& target_type() const noexcept = 0;

        virtual std::type_info const& target_type() const noexcept = 0;

    };

    };

    template<class Ex>

    template<class Ex>

    struct impl final : impl_base

    struct impl final : impl_base

    {

    {

        Ex ex_;

        Ex ex_;

        template<class Ex1>

        template<class Ex1>

        {

        {

        {

        {

        }

        }

        {

        {

        {

        {

        {

        {

        }

        }

        {

        {

        {

        {

        }

        }

        {

        {

        }

        }

    };

    };

public:

public:

    /** Construct a default instance.

    /** Construct a default instance.

        Constructs an empty `any_executor`. Calling any executor

        Constructs an empty `any_executor`. Calling any executor

        operations on a default-constructed instance results in

        operations on a default-constructed instance results in

        undefined behavior.

        undefined behavior.

        @par Postconditions

        @par Postconditions

        @li `!*this`

        @li `!*this`

    */

    */

    any_executor() = default;

    any_executor() = default;

    /** Construct a copy.

    /** Construct a copy.

        Creates a new `any_executor` sharing ownership of the

        Creates a new `any_executor` sharing ownership of the

        underlying executor with `other`.

        underlying executor with `other`.

        @par Postconditions

        @par Postconditions

        @li `*this == other`

        @li `*this == other`

    */

    */

    /** Copy assignment operator.

    /** Copy assignment operator.

        Shares ownership of the underlying executor with `other`.

        Shares ownership of the underlying executor with `other`.

        @par Postconditions

        @par Postconditions

        @li `*this == other`

        @li `*this == other`

    */

    */

    /** Constructs from any executor type.

    /** Constructs from any executor type.

        Allocates storage for a copy of the given executor and

        Allocates storage for a copy of the given executor and

        stores it internally. The executor must satisfy the

        stores it internally. The executor must satisfy the

        `Executor` concept.

        `Executor` concept.

        @param ex The executor to wrap. A copy is stored internally.

        @param ex The executor to wrap. A copy is stored internally.

        @par Postconditions

        @par Postconditions

        @li `*this` is valid

        @li `*this` is valid

    */

    */

    template<class Ex>

    template<class Ex>

        requires (

        requires (

            !std::same_as<std::decay_t<Ex>, any_executor> &&

            !std::same_as<std::decay_t<Ex>, any_executor> &&

            !detail::is_strand_type<std::decay_t<Ex>>::value &&

            !detail::is_strand_type<std::decay_t<Ex>>::value &&

            std::copy_constructible<std::decay_t<Ex>>)

            std::copy_constructible<std::decay_t<Ex>>)

    {

    {

    /** Returns true if this instance holds a valid executor.

    /** Returns true if this instance holds a valid executor.

        @return `true` if constructed with an executor, `false` if

        @return `true` if constructed with an executor, `false` if

                default-constructed.

                default-constructed.

    */

    */

    {

    {

    }

    }

    /** Returns a reference to the associated execution context.

    /** Returns a reference to the associated execution context.

        @return A reference to the execution context.

        @return A reference to the execution context.

        @pre This instance holds a valid executor.

        @pre This instance holds a valid executor.

    */

    */

    {

    {

    }

    }

    /** Informs the executor that work is beginning.

    /** Informs the executor that work is beginning.

        Must be paired with a subsequent call to `on_work_finished()`.

        Must be paired with a subsequent call to `on_work_finished()`.

        @pre This instance holds a valid executor.

        @pre This instance holds a valid executor.

    */

    */

    {

    {

    /** Informs the executor that work has completed.

    /** Informs the executor that work has completed.

        @pre A preceding call to `on_work_started()` was made.

        @pre A preceding call to `on_work_started()` was made.

        @pre This instance holds a valid executor.

        @pre This instance holds a valid executor.

    */

    */

    {

    {

    /** Dispatches a continuation through the wrapped executor.

    /** Dispatches a continuation through the wrapped executor.

        Returns a handle for symmetric transfer. If running in the

        Returns a handle for symmetric transfer. If running in the

        executor's thread, returns `c.h`. Otherwise, posts the

        executor's thread, returns `c.h`. Otherwise, posts the

        continuation for later execution and returns

        continuation for later execution and returns

        `std::noop_coroutine()`.

        `std::noop_coroutine()`.

        @param c The continuation to dispatch for resumption.

        @param c The continuation to dispatch for resumption.

                 Must remain at a stable address until dequeued.

                 Must remain at a stable address until dequeued.

        @return A handle for symmetric transfer or `std::noop_coroutine()`.

        @return A handle for symmetric transfer or `std::noop_coroutine()`.

        @pre This instance holds a valid executor.

        @pre This instance holds a valid executor.

    */

    */

    {

    {

    }

    }

    /** Posts a continuation to the wrapped executor.

    /** Posts a continuation to the wrapped executor.

        Posts the continuation to the executor for later execution

        Posts the continuation to the executor for later execution

        and returns. The caller should transfer to `std::noop_coroutine()`

        and returns. The caller should transfer to `std::noop_coroutine()`

        after calling this.

        after calling this.

        @param c The continuation to post for resumption.

        @param c The continuation to post for resumption.

                 Must remain at a stable address until dequeued.

                 Must remain at a stable address until dequeued.

        @pre This instance holds a valid executor.

        @pre This instance holds a valid executor.

    */

    */

    {

    {

    /** Compares two executor wrappers for equality.

    /** Compares two executor wrappers for equality.

        Two `any_executor` instances are equal if they both hold

        Two `any_executor` instances are equal if they both hold

        executors of the same type that compare equal, or if both

        executors of the same type that compare equal, or if both

        are empty.

        are empty.

        @param other The executor to compare against.

        @param other The executor to compare against.

        @return `true` if both wrap equal executors of the same type,

        @return `true` if both wrap equal executors of the same type,

                or both are empty.

                or both are empty.

    */

    */

    {

    {

    }

    }

    /** Returns the type_info of the wrapped executor.

    /** Returns the type_info of the wrapped executor.

        @return The `std::type_info` of the stored executor type,

        @return The `std::type_info` of the stored executor type,

                or `typeid(void)` if empty.

                or `typeid(void)` if empty.

    */

    */

    {

    {

    }

    }

};

};

} // capy

} // capy

} // boost

} // boost

#endif

#endif