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_EXECUTION_CONTEXT_HPP

#ifndef BOOST_CAPY_EXECUTION_CONTEXT_HPP

#define BOOST_CAPY_EXECUTION_CONTEXT_HPP

#define BOOST_CAPY_EXECUTION_CONTEXT_HPP

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

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

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

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

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

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

#include <boost/capy/concept/executor.hpp>

#include <boost/capy/concept/executor.hpp>

#include <concepts>

#include <concepts>

#include <memory>

#include <memory>

#include <memory_resource>

#include <memory_resource>

#include <mutex>

#include <mutex>

#include <tuple>

#include <tuple>

#include <type_traits>

#include <type_traits>

#include <utility>

#include <utility>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

/** Base class for I/O object containers providing service management.

/** Base class for I/O object containers providing service management.

    An execution context represents a place where function objects are

    An execution context represents a place where function objects are

    executed. It provides a service registry where polymorphic services

    executed. It provides a service registry where polymorphic services

    can be stored and retrieved by type. Each service type may be stored

    can be stored and retrieved by type. Each service type may be stored

    at most once. Services may specify a nested `key_type` to enable

    at most once. Services may specify a nested `key_type` to enable

    lookup by a base class type.

    lookup by a base class type.

    Derived classes such as `io_context` extend this to provide

    Derived classes such as `io_context` extend this to provide

    execution facilities like event loops and thread pools. Derived

    execution facilities like event loops and thread pools. Derived

    class destructors must call `shutdown()` and `destroy()` to ensure

    class destructors must call `shutdown()` and `destroy()` to ensure

    proper service cleanup before member destruction.

    proper service cleanup before member destruction.

    @par Service Lifecycle

    @par Service Lifecycle

    Services are created on first use via `use_service()` or explicitly

    Services are created on first use via `use_service()` or explicitly

    via `make_service()`. During destruction, `shutdown()` is called on

    via `make_service()`. During destruction, `shutdown()` is called on

    each service in reverse order of creation, then `destroy()` deletes

    each service in reverse order of creation, then `destroy()` deletes

    them. Both functions are idempotent.

    them. Both functions are idempotent.

    @par Thread Safety

    @par Thread Safety

    Service registration and lookup functions are thread-safe.

    Service registration and lookup functions are thread-safe.

    The `shutdown()` and `destroy()` functions are not thread-safe

    The `shutdown()` and `destroy()` functions are not thread-safe

    and must only be called during destruction.

    and must only be called during destruction.

    @par Example

    @par Example

    @code

    @code

    struct file_service : execution_context::service

    struct file_service : execution_context::service

    {

    {

    protected:

    protected:

        void shutdown() override {}

        void shutdown() override {}

    };

    };

    struct posix_file_service : file_service

    struct posix_file_service : file_service

    {

    {

        using key_type = file_service;

        using key_type = file_service;

        explicit posix_file_service(execution_context&) {}

        explicit posix_file_service(execution_context&) {}

    };

    };

    class io_context : public execution_context

    class io_context : public execution_context

    {

    {

    public:

    public:

        ~io_context()

        ~io_context()

        {

        {

            shutdown();

            shutdown();

            destroy();

            destroy();

        }

        }

    };

    };

    io_context ctx;

    io_context ctx;

    ctx.make_service<posix_file_service>();

    ctx.make_service<posix_file_service>();

    ctx.find_service<file_service>();       // returns posix_file_service*

    ctx.find_service<file_service>();       // returns posix_file_service*

    ctx.find_service<posix_file_service>(); // also works

    ctx.find_service<posix_file_service>(); // also works

    @endcode

    @endcode

    @see service, is_execution_context

    @see service, is_execution_context

*/

*/

class BOOST_CAPY_DECL

class BOOST_CAPY_DECL

    execution_context

    execution_context

{

{

    template<class T, class = void>

    template<class T, class = void>

    struct get_key : std::false_type

    struct get_key : std::false_type

    {};

    {};

    template<class T>

    template<class T>

    struct get_key<T, std::void_t<typename T::key_type>> : std::true_type

    struct get_key<T, std::void_t<typename T::key_type>> : std::true_type

    {

    {

        using type = typename T::key_type;

        using type = typename T::key_type;

    };

    };

public:

public:

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

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

    /** Abstract base class for services owned by an execution context.

    /** Abstract base class for services owned by an execution context.

        Services provide extensible functionality to an execution context.

        Services provide extensible functionality to an execution context.

        Each service type can be registered at most once. Services are

        Each service type can be registered at most once. Services are

        created via `use_service()` or `make_service()` and are owned by

        created via `use_service()` or `make_service()` and are owned by

        the execution context for their lifetime.

        the execution context for their lifetime.

        Derived classes must implement the pure virtual `shutdown()` member

        Derived classes must implement the pure virtual `shutdown()` member

        function, which is called when the owning execution context is

        function, which is called when the owning execution context is

        being destroyed. The `shutdown()` function should release resources

        being destroyed. The `shutdown()` function should release resources

        and cancel outstanding operations without blocking.

        and cancel outstanding operations without blocking.

        @par Deriving from service

        @par Deriving from service

        @li Implement `shutdown()` to perform cleanup.

        @li Implement `shutdown()` to perform cleanup.

        @li Accept `execution_context&` as the first constructor parameter.

        @li Accept `execution_context&` as the first constructor parameter.

        @li Optionally define `key_type` to enable base-class lookup.

        @li Optionally define `key_type` to enable base-class lookup.

        @par Example

        @par Example

        @code

        @code

        struct my_service : execution_context::service

        struct my_service : execution_context::service

        {

        {

            explicit my_service(execution_context&) {}

            explicit my_service(execution_context&) {}

        protected:

        protected:

            void shutdown() override

            void shutdown() override

            {

            {

                // Cancel pending operations, release resources

                // Cancel pending operations, release resources

            }

            }

        };

        };

        @endcode

        @endcode

        @see execution_context

        @see execution_context

    */

    */

    class BOOST_CAPY_DECL

    class BOOST_CAPY_DECL

        service

        service

    {

    {

    public:

    public:

    protected:

    protected:

        /** Called when the owning execution context shuts down.

        /** Called when the owning execution context shuts down.

            Implementations should release resources and cancel any

            Implementations should release resources and cancel any

            outstanding asynchronous operations. This function must

            outstanding asynchronous operations. This function must

            not block and must not throw exceptions. Services are

            not block and must not throw exceptions. Services are

            shut down in reverse order of creation.

            shut down in reverse order of creation.

            @par Exception Safety

            @par Exception Safety

            No-throw guarantee.

            No-throw guarantee.

        */

        */

        virtual void shutdown() = 0;

        virtual void shutdown() = 0;

    private:

    private:

        friend class execution_context;

        friend class execution_context;

        service* next_ = nullptr;

        service* next_ = nullptr;

// warning C4251: 'std::type_index' needs to have dll-interface

// warning C4251: 'std::type_index' needs to have dll-interface

#ifdef _MSC_VER

#ifdef _MSC_VER

# pragma warning(push)

# pragma warning(push)

# pragma warning(disable: 4251)

# pragma warning(disable: 4251)

#endif

#endif

        detail::type_index t0_{detail::type_id<void>()};

        detail::type_index t0_{detail::type_id<void>()};

        detail::type_index t1_{detail::type_id<void>()};

        detail::type_index t1_{detail::type_id<void>()};

#ifdef _MSC_VER

#ifdef _MSC_VER

# pragma warning(pop)

# pragma warning(pop)

#endif

#endif

    };

    };

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

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

    execution_context(execution_context const&) = delete;

    execution_context(execution_context const&) = delete;

    execution_context& operator=(execution_context const&) = delete;

    execution_context& operator=(execution_context const&) = delete;

    /** Destructor.

    /** Destructor.

        Calls `shutdown()` then `destroy()` to clean up all services.

        Calls `shutdown()` then `destroy()` to clean up all services.

        @par Effects

        @par Effects

        All services are shut down and deleted in reverse order

        All services are shut down and deleted in reverse order

        of creation.

        of creation.

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

    */

    */

    ~execution_context();

    ~execution_context();

    /** Default constructor.

    /** Default constructor.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

    */

    */

    execution_context();

    execution_context();

    /** Return true if a service of type T exists.

    /** Return true if a service of type T exists.

        @par Thread Safety

        @par Thread Safety

        Thread-safe.

        Thread-safe.

        @tparam T The type of service to check.

        @tparam T The type of service to check.

        @return `true` if the service exists.

        @return `true` if the service exists.

    */

    */

    template<class T>

    template<class T>

    {

    {

    }

    }

    /** Return a pointer to the service of type T, or nullptr.

    /** Return a pointer to the service of type T, or nullptr.

        @par Thread Safety

        @par Thread Safety

        Thread-safe.

        Thread-safe.

        @tparam T The type of service to find.

        @tparam T The type of service to find.

        @return A pointer to the service, or `nullptr` if not present.

        @return A pointer to the service, or `nullptr` if not present.

    */

    */

    template<class T>

    template<class T>

    {

    {

    /** Return a reference to the service of type T, creating it if needed.

    /** Return a reference to the service of type T, creating it if needed.

        If no service of type T exists, one is created by calling

        If no service of type T exists, one is created by calling

        `T(execution_context&)`. If T has a nested `key_type`, the

        `T(execution_context&)`. If T has a nested `key_type`, the

        service is also indexed under that type.

        service is also indexed under that type.

        @par Constraints

        @par Constraints

        @li `T` must derive from `service`.

        @li `T` must derive from `service`.

        @li `T` must be constructible from `execution_context&`.

        @li `T` must be constructible from `execution_context&`.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee. If service creation throws, the container

        Strong guarantee. If service creation throws, the container

        is unchanged.

        is unchanged.

        @par Thread Safety

        @par Thread Safety

        Thread-safe.

        Thread-safe.

        @tparam T The type of service to retrieve or create.

        @tparam T The type of service to retrieve or create.

        @return A reference to the service.

        @return A reference to the service.

    */

    */

    template<class T>

    template<class T>

    {

    {

        static_assert(std::is_base_of<service, T>::value,

        static_assert(std::is_base_of<service, T>::value,

            "T must derive from service");

            "T must derive from service");

        static_assert(std::is_constructible<T, execution_context&>::value,

        static_assert(std::is_constructible<T, execution_context&>::value,

            "T must be constructible from execution_context&");

            "T must be constructible from execution_context&");

        struct impl : factory

        struct impl : factory

        {

        {

                : factory(

                : factory(

                    detail::type_id<T>(),

                    detail::type_id<T>(),

                    get_key<T>::value

                    get_key<T>::value

                        ? detail::type_id<typename get_key<T>::type>()

                        ? detail::type_id<typename get_key<T>::type>()

            {

            {

            {

            {

            }

            }

        };

        };

    }

    }

    /** Construct and add a service.

    /** Construct and add a service.

        A new service of type T is constructed using the provided

        A new service of type T is constructed using the provided

        arguments and added to the container. If T has a nested

        arguments and added to the container. If T has a nested

        `key_type`, the service is also indexed under that type.

        `key_type`, the service is also indexed under that type.

        @par Constraints

        @par Constraints

        @li `T` must derive from `service`.

        @li `T` must derive from `service`.

        @li `T` must be constructible from `execution_context&, Args...`.

        @li `T` must be constructible from `execution_context&, Args...`.

        @li If `T::key_type` exists, `T&` must be convertible to `key_type&`.

        @li If `T::key_type` exists, `T&` must be convertible to `key_type&`.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee. If service creation throws, the container

        Strong guarantee. If service creation throws, the container

        is unchanged.

        is unchanged.

        @par Thread Safety

        @par Thread Safety

        Thread-safe.

        Thread-safe.

        @throws std::invalid_argument if a service of the same type

        @throws std::invalid_argument if a service of the same type

            or `key_type` already exists.

            or `key_type` already exists.

        @tparam T The type of service to create.

        @tparam T The type of service to create.

        @param args Arguments forwarded to the constructor of T.

        @param args Arguments forwarded to the constructor of T.

        @return A reference to the created service.

        @return A reference to the created service.

    */

    */

    template<class T, class... Args>

    template<class T, class... Args>

    {

    {

        static_assert(std::is_base_of<service, T>::value,

        static_assert(std::is_base_of<service, T>::value,

            "T must derive from service");

            "T must derive from service");

        if constexpr(get_key<T>::value)

        if constexpr(get_key<T>::value)

        {

        {

            static_assert(

            static_assert(

                std::is_convertible<T&, typename get_key<T>::type&>::value,

                std::is_convertible<T&, typename get_key<T>::type&>::value,

                "T& must be convertible to key_type&");

                "T& must be convertible to key_type&");

        }

        }

        struct impl : factory

        struct impl : factory

        {

        {

            std::tuple<Args&&...> args_;

            std::tuple<Args&&...> args_;

                : factory(

                : factory(

                    detail::type_id<T>(),

                    detail::type_id<T>(),

                    get_key<T>::value

                    get_key<T>::value

                        ? detail::type_id<typename get_key<T>::type>()

                        ? detail::type_id<typename get_key<T>::type>()

                        : detail::type_id<T>())

                        : detail::type_id<T>())

            {

            {

            {

            {

            }

            }

        };

        };

    }

    }

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

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

    /** Return the memory resource used for coroutine frame allocation.

    /** Return the memory resource used for coroutine frame allocation.

        The returned pointer is valid for the lifetime of this context.

        The returned pointer is valid for the lifetime of this context.

        By default, this returns a pointer to the recycling memory

        By default, this returns a pointer to the recycling memory

        resource which pools frame allocations for reuse.

        resource which pools frame allocations for reuse.

        @return Pointer to the frame allocator.

        @return Pointer to the frame allocator.

        @see set_frame_allocator

        @see set_frame_allocator

    */

    */

    std::pmr::memory_resource*

    std::pmr::memory_resource*

    {

    {

    }

    }

    /** Set the memory resource used for coroutine frame allocation.

    /** Set the memory resource used for coroutine frame allocation.

        The caller is responsible for ensuring the memory resource

        The caller is responsible for ensuring the memory resource

        remains valid for the lifetime of all coroutines launched

        remains valid for the lifetime of all coroutines launched

        using this context's executor.

        using this context's executor.

        @par Thread Safety

        @par Thread Safety

        Not thread-safe. Must not be called while any thread may

        Not thread-safe. Must not be called while any thread may

        be referencing this execution context or its executor.

        be referencing this execution context or its executor.

        @param mr Pointer to the memory resource.

        @param mr Pointer to the memory resource.

        @see get_frame_allocator

        @see get_frame_allocator

    */

    */

    void

    void

    set_frame_allocator(std::pmr::memory_resource* mr) noexcept

    set_frame_allocator(std::pmr::memory_resource* mr) noexcept

    {

    {

        owned_.reset();

        owned_.reset();

        frame_alloc_ = mr;

        frame_alloc_ = mr;

    }

    }

    /** Set the frame allocator from a standard Allocator.

    /** Set the frame allocator from a standard Allocator.

        The allocator is wrapped in an internal memory resource

        The allocator is wrapped in an internal memory resource

        adapter owned by this context. The wrapper remains valid

        adapter owned by this context. The wrapper remains valid

        for the lifetime of this context or until a subsequent

        for the lifetime of this context or until a subsequent

        call to set_frame_allocator.

        call to set_frame_allocator.

        @par Thread Safety

        @par Thread Safety

        Not thread-safe. Must not be called while any thread may

        Not thread-safe. Must not be called while any thread may

        be referencing this execution context or its executor.

        be referencing this execution context or its executor.

        @tparam Allocator The allocator type satisfying the

        @tparam Allocator The allocator type satisfying the

            standard Allocator requirements.

            standard Allocator requirements.

        @param a The allocator to use.

        @param a The allocator to use.

        @see get_frame_allocator

        @see get_frame_allocator

    */

    */

    template<class Allocator>

    template<class Allocator>

        requires (!std::is_pointer_v<Allocator>)

        requires (!std::is_pointer_v<Allocator>)

    void

    void

    {

    {

        static_assert(

        static_assert(

            requires { typename std::allocator_traits<Allocator>::value_type; },

            requires { typename std::allocator_traits<Allocator>::value_type; },

            "Allocator must satisfy allocator requirements");

            "Allocator must satisfy allocator requirements");

        static_assert(

        static_assert(

            std::is_copy_constructible_v<Allocator>,

            std::is_copy_constructible_v<Allocator>,

            "Allocator must be copy constructible");

            "Allocator must be copy constructible");

            detail::frame_memory_resource<Allocator>>(a);

            detail::frame_memory_resource<Allocator>>(a);

protected:

protected:

    /** Shut down all services.

    /** Shut down all services.

        Calls `shutdown()` on each service in reverse order of creation.

        Calls `shutdown()` on each service in reverse order of creation.

        After this call, services remain allocated but are in a stopped

        After this call, services remain allocated but are in a stopped

        state. Derived classes should call this in their destructor

        state. Derived classes should call this in their destructor

        before any members are destroyed. This function is idempotent;

        before any members are destroyed. This function is idempotent;

        subsequent calls have no effect.

        subsequent calls have no effect.

        @par Effects

        @par Effects

        Each service's `shutdown()` member function is invoked once.

        Each service's `shutdown()` member function is invoked once.

        @par Postconditions

        @par Postconditions

        @li All services are in a stopped state.

        @li All services are in a stopped state.

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

        @par Thread Safety

        @par Thread Safety

        Not thread-safe. Must not be called concurrently with other

        Not thread-safe. Must not be called concurrently with other

        operations on this execution_context.

        operations on this execution_context.

    */

    */

    void shutdown() noexcept;

    void shutdown() noexcept;

    /** Destroy all services.

    /** Destroy all services.

        Deletes all services in reverse order of creation. Derived

        Deletes all services in reverse order of creation. Derived

        classes should call this as the final step of destruction.

        classes should call this as the final step of destruction.

        This function is idempotent; subsequent calls have no effect.

        This function is idempotent; subsequent calls have no effect.

        @par Preconditions

        @par Preconditions

        @li `shutdown()` has been called.

        @li `shutdown()` has been called.

        @par Effects

        @par Effects

        All services are deleted and removed from the container.

        All services are deleted and removed from the container.

        @par Postconditions

        @par Postconditions

        @li The service container is empty.

        @li The service container is empty.

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

        @par Thread Safety

        @par Thread Safety

        Not thread-safe. Must not be called concurrently with other

        Not thread-safe. Must not be called concurrently with other

        operations on this execution_context.

        operations on this execution_context.

    */

    */

    void destroy() noexcept;

    void destroy() noexcept;

private:

private:

    struct BOOST_CAPY_DECL

    struct BOOST_CAPY_DECL

        factory

        factory

    {

    {

#ifdef _MSC_VER

#ifdef _MSC_VER

# pragma warning(push)

# pragma warning(push)

# pragma warning(disable: 4251)

# pragma warning(disable: 4251)

#endif

#endif

// warning C4251: 'std::type_index' needs to have dll-interface

// warning C4251: 'std::type_index' needs to have dll-interface

        detail::type_index t0;

        detail::type_index t0;

        detail::type_index t1;

        detail::type_index t1;

#ifdef _MSC_VER

#ifdef _MSC_VER

# pragma warning(pop)

# pragma warning(pop)

#endif

#endif

            detail::type_info const& t0_,

            detail::type_info const& t0_,

            detail::type_info const& t1_)

            detail::type_info const& t1_)

        {

        {

        virtual service* create(execution_context&) = 0;

        virtual service* create(execution_context&) = 0;

    protected:

    protected:

        ~factory() = default;

        ~factory() = default;

    };

    };

    service* find_impl(detail::type_index ti) const noexcept;

    service* find_impl(detail::type_index ti) const noexcept;

    service& use_service_impl(factory& f);

    service& use_service_impl(factory& f);

    service& make_service_impl(factory& f);

    service& make_service_impl(factory& f);

#ifdef _MSC_VER

#ifdef _MSC_VER

# pragma warning(push)

# pragma warning(push)

# pragma warning(disable: 4251)

# pragma warning(disable: 4251)

#endif

#endif

// warning C4251: 'std::type_index' needs to have dll-interface

// warning C4251: 'std::type_index' needs to have dll-interface

    mutable std::mutex mutex_;

    mutable std::mutex mutex_;

    std::shared_ptr<void> owned_;

    std::shared_ptr<void> owned_;

#ifdef _MSC_VER

#ifdef _MSC_VER

# pragma warning(pop)

# pragma warning(pop)

#endif

#endif

    std::pmr::memory_resource* frame_alloc_ = nullptr;

    std::pmr::memory_resource* frame_alloc_ = nullptr;

    service* head_ = nullptr;

    service* head_ = nullptr;

    bool shutdown_ = false;

    bool shutdown_ = false;

};

};

} // namespace capy

} // namespace capy

} // namespace boost

} // namespace boost

#endif

#endif