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_EXECUTOR_REF_HPP

#ifndef BOOST_CAPY_EXECUTOR_REF_HPP

#define BOOST_CAPY_EXECUTOR_REF_HPP

#define BOOST_CAPY_EXECUTOR_REF_HPP

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

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

#include <boost/capy/coro.hpp>

#include <boost/capy/coro.hpp>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <type_traits>

#include <type_traits>

#include <utility>

#include <utility>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

class execution_context;

class execution_context;

namespace detail {

namespace detail {

/** Virtual function table for type-erased executor operations. */

/** Virtual function table for type-erased executor operations. */

struct executor_vtable

struct executor_vtable

{

{

    execution_context& (*context)(void const*) noexcept;

    execution_context& (*context)(void const*) noexcept;

    void (*on_work_started)(void const*) noexcept;

    void (*on_work_started)(void const*) noexcept;

    void (*on_work_finished)(void const*) noexcept;

    void (*on_work_finished)(void const*) noexcept;

    void (*post)(void const*, std::coroutine_handle<>);

    void (*post)(void const*, std::coroutine_handle<>);

    void (*dispatch)(void const*, std::coroutine_handle<>);

    void (*dispatch)(void const*, std::coroutine_handle<>);

    bool (*equals)(void const*, void const*) noexcept;

    bool (*equals)(void const*, void const*) noexcept;

};

};

/** Vtable instance for a specific executor type. */

/** Vtable instance for a specific executor type. */

template<class Ex>

template<class Ex>

inline constexpr executor_vtable vtable_for = {

inline constexpr executor_vtable vtable_for = {

    // context

    // context

    },

    },

    // on_work_started

    // on_work_started

    },

    },

    // on_work_finished

    // on_work_finished

    },

    },

    // post

    // post

    },

    },

    // dispatch

    // dispatch

    },

    },

    // equals

    // equals

    }

    }

};

};

} // detail

} // detail

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

/** A type-erased reference 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 without virtual functions or allocation.

    runtime polymorphism without virtual functions or allocation.

    It stores a pointer to the original executor and a pointer to a

    It stores a pointer to the original executor and a pointer to a

    static vtable, allowing executors of different types to be stored

    static vtable, allowing executors of different types to be stored

    uniformly while satisfying the full `Executor` concept.

    uniformly while satisfying the full `Executor` concept.

    @par Reference Semantics

    @par Reference Semantics

    This class has reference semantics: it does not allocate or own

    This class has reference semantics: it does not allocate or own

    the wrapped executor. Copy operations simply copy the internal

    the wrapped executor. Copy operations simply copy the internal

    pointers. The caller must ensure the referenced executor outlives

    pointers. The caller must ensure the referenced executor outlives

    all `executor_ref` instances that wrap it.

    all `executor_ref` instances that wrap it.

    @par Thread Safety

    @par Thread Safety

    The `executor_ref` itself is not thread-safe for concurrent

    The `executor_ref` itself is not thread-safe for concurrent

    modification, but its executor operations are safe to call

    modification, but its executor operations are safe to call

    concurrently if the underlying executor supports it.

    concurrently if the 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

    void store_executor(executor_ref ex)

    void store_executor(executor_ref ex)

    {

    {

        if(ex)

        if(ex)

            ex.post(my_coroutine);

            ex.post(my_coroutine);

    }

    }

    io_context ctx;

    io_context ctx;

    store_executor(ctx.get_executor());

    store_executor(ctx.get_executor());

    @endcode

    @endcode

    @see any_executor, Executor

    @see any_executor, Executor

*/

*/

class executor_ref

class executor_ref

{

{

    void const* ex_ = nullptr;

    void const* ex_ = nullptr;

    detail::executor_vtable const* vt_ = nullptr;

    detail::executor_vtable const* vt_ = nullptr;

public:

public:

    /** Default constructor.

    /** Default constructor.

        Constructs an empty `executor_ref`. Calling any executor

        Constructs an empty `executor_ref`. Calling any executor

        operations on a default-constructed instance results in

        operations on a default-constructed instance results in

        undefined behavior.

        undefined behavior.

    */

    */

    /** Copy constructor.

    /** Copy constructor.

        Copies the internal pointers, preserving identity.

        Copies the internal pointers, preserving identity.

        This enables the same-executor optimization when passing

        This enables the same-executor optimization when passing

        executor_ref through coroutine chains.

        executor_ref through coroutine chains.

    */

    */

    executor_ref(executor_ref const&) = default;

    executor_ref(executor_ref const&) = default;

    /** Copy assignment operator. */

    /** Copy assignment operator. */

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

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

    /** Constructs from any executor type.

    /** Constructs from any executor type.

        Captures a reference to the given executor and stores a pointer

        Captures a reference to the given executor and stores a pointer

        to the type-specific vtable. The executor must remain valid for

        to the type-specific vtable. The executor must remain valid for

        the lifetime of this `executor_ref` instance.

        the lifetime of this `executor_ref` instance.

        @param ex The executor to wrap. Must satisfy the `Executor`

        @param ex The executor to wrap. Must satisfy the `Executor`

                  concept. A pointer to this object is stored

                  concept. A pointer to this object is stored

                  internally; the executor must outlive this wrapper.

                  internally; the executor must outlive this wrapper.

    */

    */

#if defined(__GNUC__) && !defined(__clang__)

#if defined(__GNUC__) && !defined(__clang__)

    // GCC constraint satisfaction caching bug workaround

    // GCC constraint satisfaction caching bug workaround

    template<class Ex,

    template<class Ex,

        std::enable_if_t<!std::is_same_v<

        std::enable_if_t<!std::is_same_v<

            std::decay_t<Ex>, executor_ref>, int> = 0>

            std::decay_t<Ex>, executor_ref>, int> = 0>

#else

#else

    template<class Ex>

    template<class Ex>

        requires (!std::same_as<std::decay_t<Ex>, executor_ref>)

        requires (!std::same_as<std::decay_t<Ex>, executor_ref>)

#endif

#endif

    {

    {

    /** 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 was constructed with a valid executor.

        @pre This instance was constructed with a valid executor.

    */

    */

    execution_context& context() const noexcept

    execution_context& context() const noexcept

    {

    {

        return vt_->context(ex_);

        return vt_->context(ex_);

    }

    }

    /** 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 was constructed with a valid executor.

        @pre This instance was constructed with a valid executor.

    */

    */

    void on_work_started() const noexcept

    void on_work_started() const noexcept

    {

    {

        vt_->on_work_started(ex_);

        vt_->on_work_started(ex_);

    }

    }

    /** 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 was constructed with a valid executor.

        @pre This instance was constructed with a valid executor.

    */

    */

    void on_work_finished() const noexcept

    void on_work_finished() const noexcept

    {

    {

        vt_->on_work_finished(ex_);

        vt_->on_work_finished(ex_);

    }

    }

    /** Dispatches a coroutine handle through the wrapped executor.

    /** Dispatches a coroutine handle through the wrapped executor.

        Invokes the executor's `dispatch()` operation with the given

        Invokes the executor's `dispatch()` operation with the given

        coroutine handle. If running in the executor's thread, resumes

        coroutine handle. If running in the executor's thread, resumes

        the coroutine inline via a normal function call. Otherwise,

        the coroutine inline via a normal function call. Otherwise,

        posts the coroutine for later execution.

        posts the coroutine for later execution.

        @param h The coroutine handle to dispatch for resumption.

        @param h The coroutine handle to dispatch for resumption.

        @pre This instance was constructed with a valid executor.

        @pre This instance was constructed with a valid executor.

    */

    */

    {

    {

    /** Posts a coroutine handle to the wrapped executor.

    /** Posts a coroutine handle to the wrapped executor.

        Posts the coroutine handle to the executor for later execution

        Posts the coroutine handle 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 h The coroutine handle to post for resumption.

        @param h The coroutine handle to post for resumption.

        @pre This instance was constructed with a valid executor.

        @pre This instance was constructed with a valid executor.

    */

    */

    {

    {

    /** Compares two executor references for equality.

    /** Compares two executor references for equality.

        Two `executor_ref` instances are equal if they wrap

        Two `executor_ref` instances are equal if they wrap

        executors of the same type that compare equal.

        executors of the same type that compare equal.

        @param other The executor reference to compare against.

        @param other The executor reference 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.

    */

    */

    {

    {

    }

    }

};

};

} // capy

} // capy

} // boost

} // boost

#endif

#endif