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_EX_IO_AWAITABLE_PROMISE_BASE_HPP

#ifndef BOOST_CAPY_EX_IO_AWAITABLE_PROMISE_BASE_HPP

#define BOOST_CAPY_EX_IO_AWAITABLE_PROMISE_BASE_HPP

#define BOOST_CAPY_EX_IO_AWAITABLE_PROMISE_BASE_HPP

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

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

#include <boost/capy/ex/frame_alloc_mixin.hpp>

#include <boost/capy/ex/frame_allocator.hpp>

#include <boost/capy/ex/frame_allocator.hpp>

#include <boost/capy/ex/recycling_memory_resource.hpp>

#include <boost/capy/ex/io_env.hpp>

#include <boost/capy/ex/io_env.hpp>

#include <boost/capy/ex/this_coro.hpp>

#include <boost/capy/ex/this_coro.hpp>

#include <cstddef>

#include <cstring>

#include <coroutine>

#include <coroutine>

#include <memory_resource>

#include <memory_resource>

#include <stop_token>

#include <stop_token>

#include <type_traits>

#include <type_traits>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

/** CRTP mixin that adds I/O awaitable support to a promise type.

/** CRTP mixin that adds I/O awaitable support to a promise type.

    Inherit from this class to enable these capabilities in your coroutine:

    Inherit from this class to enable these capabilities in your coroutine:

    1. **Frame allocation** — The mixin provides `operator new/delete` that

    1. **Frame allocation** — The mixin provides `operator new/delete` that

       use the thread-local frame allocator set by `run_async`.

       use the thread-local frame allocator set by `run_async`.

    2. **Environment storage** — The mixin stores a pointer to the `io_env`

    2. **Environment storage** — The mixin stores a pointer to the `io_env`

       containing the executor, stop token, and allocator for this coroutine.

       containing the executor, stop token, and allocator for this coroutine.

    3. **Environment access** — Coroutine code can retrieve the environment

    3. **Environment access** — Coroutine code can retrieve the environment

       via `co_await this_coro::environment`, or individual fields via

       via `co_await this_coro::environment`, or individual fields via

       `co_await this_coro::executor`, `co_await this_coro::stop_token`,

       `co_await this_coro::executor`, `co_await this_coro::stop_token`,

       and `co_await this_coro::frame_allocator`.

       and `co_await this_coro::frame_allocator`.

    @tparam Derived The derived promise type (CRTP pattern).

    @tparam Derived The derived promise type (CRTP pattern).

    @par Basic Usage

    @par Basic Usage

    For coroutines that need to access their execution environment:

    For coroutines that need to access their execution environment:

    @code

    @code

    struct my_task

    struct my_task

    {

    {

        struct promise_type : io_awaitable_promise_base<promise_type>

        struct promise_type : io_awaitable_promise_base<promise_type>

        {

        {

            my_task get_return_object();

            my_task get_return_object();

            std::suspend_always initial_suspend() noexcept;

            std::suspend_always initial_suspend() noexcept;

            std::suspend_always final_suspend() noexcept;

            std::suspend_always final_suspend() noexcept;

            void return_void();

            void return_void();

            void unhandled_exception();

            void unhandled_exception();

        };

        };

        // ... awaitable interface ...

        // ... awaitable interface ...

    };

    };

    my_task example()

    my_task example()

    {

    {

        auto env = co_await this_coro::environment;

        auto env = co_await this_coro::environment;

        // Access env->executor, env->stop_token, env->frame_allocator

        // Access env->executor, env->stop_token, env->frame_allocator

        // Or use fine-grained accessors:

        // Or use fine-grained accessors:

        auto ex = co_await this_coro::executor;

        auto ex = co_await this_coro::executor;

        auto token = co_await this_coro::stop_token;

        auto token = co_await this_coro::stop_token;

        auto* alloc = co_await this_coro::frame_allocator;

        auto* alloc = co_await this_coro::frame_allocator;

    }

    }

    @endcode

    @endcode

    @par Custom Awaitable Transformation

    @par Custom Awaitable Transformation

    If your promise needs to transform awaitables (e.g., for affinity or

    If your promise needs to transform awaitables (e.g., for affinity or

    logging), override `transform_awaitable` instead of `await_transform`:

    logging), override `transform_awaitable` instead of `await_transform`:

    @code

    @code

    struct promise_type : io_awaitable_promise_base<promise_type>

    struct promise_type : io_awaitable_promise_base<promise_type>

    {

    {

        template<typename A>

        template<typename A>

        auto transform_awaitable(A&& a)

        auto transform_awaitable(A&& a)

        {

        {

            // Your custom transformation logic

            // Your custom transformation logic

            return std::forward<A>(a);

            return std::forward<A>(a);

        }

        }

    };

    };

    @endcode

    @endcode

    The mixin's `await_transform` intercepts @ref this_coro::environment_tag

    The mixin's `await_transform` intercepts @ref this_coro::environment_tag

    and the fine-grained tag types (@ref this_coro::executor_tag,

    and the fine-grained tag types (@ref this_coro::executor_tag,

    @ref this_coro::stop_token_tag, @ref this_coro::frame_allocator_tag),

    @ref this_coro::stop_token_tag, @ref this_coro::frame_allocator_tag),

    then delegates all other awaitables to your `transform_awaitable`.

    then delegates all other awaitables to your `transform_awaitable`.

    @par Making Your Coroutine an IoAwaitable

    @par Making Your Coroutine an IoAwaitable

    The mixin handles the "inside the coroutine" part—accessing the

    The mixin handles the "inside the coroutine" part—accessing the

    environment. To receive the environment when your coroutine is awaited

    environment. To receive the environment when your coroutine is awaited

    (satisfying @ref IoAwaitable), implement the `await_suspend` overload

    (satisfying @ref IoAwaitable), implement the `await_suspend` overload

    on your coroutine return type:

    on your coroutine return type:

    @code

    @code

    struct my_task

    struct my_task

    {

    {

        struct promise_type : io_awaitable_promise_base<promise_type> { ... };

        struct promise_type : io_awaitable_promise_base<promise_type> { ... };

        std::coroutine_handle<promise_type> h_;

        std::coroutine_handle<promise_type> h_;

        // IoAwaitable await_suspend receives and stores the environment

        // IoAwaitable await_suspend receives and stores the environment

        std::coroutine_handle<> await_suspend(std::coroutine_handle<> cont, io_env const* env)

        std::coroutine_handle<> await_suspend(std::coroutine_handle<> cont, io_env const* env)

        {

        {

            h_.promise().set_environment(env);

            h_.promise().set_environment(env);

            // ... rest of suspend logic ...

            // ... rest of suspend logic ...

        }

        }

    };

    };

    @endcode

    @endcode

    @par Thread Safety

    @par Thread Safety

    The environment is stored during `await_suspend` and read during

    The environment is stored during `await_suspend` and read during

    `co_await this_coro::environment`. These occur on the same logical

    `co_await this_coro::environment`. These occur on the same logical

    thread of execution, so no synchronization is required.

    thread of execution, so no synchronization is required.

    @see this_coro::environment, this_coro::executor,

    @see this_coro::environment, this_coro::executor,

         this_coro::stop_token, this_coro::frame_allocator

         this_coro::stop_token, this_coro::frame_allocator

    @see io_env

    @see io_env

    @see IoAwaitable

    @see IoAwaitable

*/

*/

template<typename Derived>

template<typename Derived>

class io_awaitable_promise_base

class io_awaitable_promise_base

    : public frame_alloc_mixin

{

{

    io_env const* env_ = nullptr;

    io_env const* env_ = nullptr;

    mutable std::coroutine_handle<> cont_{std::noop_coroutine()};

    mutable std::coroutine_handle<> cont_{std::noop_coroutine()};

    /** Allocate a coroutine frame.

        Uses the thread-local frame allocator set by run_async.

        Falls back to default memory resource if not set.

        Stores the allocator pointer at the end of each frame for

        correct deallocation even when TLS changes. Uses memcpy

        to avoid alignment requirements on the trailing pointer.

        Bypasses virtual dispatch for the recycling allocator.

    */

    static void* operator new(std::size_t size)

        static auto* const rmr = get_recycling_memory_resource();

        auto* mr = get_current_frame_allocator();

        auto total = size + sizeof(std::pmr::memory_resource*);

        if(mr == rmr)

                ->allocate_fast(total, alignof(std::max_align_t));

            raw = mr->allocate(total, alignof(std::max_align_t));

    /** Deallocate a coroutine frame.

        Reads the allocator pointer stored at the end of the frame

        to ensure correct deallocation regardless of current TLS.

        Bypasses virtual dispatch for the recycling allocator.

    */

    static void operator delete(void* ptr, std::size_t size) noexcept

        static auto* const rmr = get_recycling_memory_resource();

        std::pmr::memory_resource* mr;

        std::memcpy(&mr, static_cast<char*>(ptr) + size, sizeof(mr));

                ->deallocate_fast(ptr, total, alignof(std::max_align_t));

            mr->deallocate(ptr, total, alignof(std::max_align_t));

public:

public:

    {

    {

        // Abnormal teardown: destroy orphaned continuation

        // Abnormal teardown: destroy orphaned continuation

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

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

    // Continuation support

    // Continuation support

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

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

    /** Store the continuation to resume on completion.

    /** Store the continuation to resume on completion.

        Call this from your coroutine type's `await_suspend` overload

        Call this from your coroutine type's `await_suspend` overload

        to set up the completion path. The `final_suspend` awaiter

        to set up the completion path. The `final_suspend` awaiter

        returns this handle via unconditional symmetric transfer.

        returns this handle via unconditional symmetric transfer.

        @param cont The continuation to resume on completion.

        @param cont The continuation to resume on completion.

    */

    */

    {

    {

    /** Return and consume the stored continuation handle.

    /** Return and consume the stored continuation handle.

        Resets the stored handle to `noop_coroutine()` so the

        Resets the stored handle to `noop_coroutine()` so the

        destructor will not double-destroy it.

        destructor will not double-destroy it.

        @return The continuation for symmetric transfer.

        @return The continuation for symmetric transfer.

    */

    */

    {

    {

    }

    }

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

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

    // Environment support

    // Environment support

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

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

    /** Store a pointer to the execution environment.

    /** Store a pointer to the execution environment.

        Call this from your coroutine type's `await_suspend`

        Call this from your coroutine type's `await_suspend`

        overload to make the environment available via

        overload to make the environment available via

        `co_await this_coro::environment`. The pointed-to

        `co_await this_coro::environment`. The pointed-to

        `io_env` must outlive this coroutine.

        `io_env` must outlive this coroutine.

        @param env The environment to store.

        @param env The environment to store.

    */

    */

    {

    {

    /** Return the stored execution environment.

    /** Return the stored execution environment.

        @return The environment.

        @return The environment.

    */

    */

    {

    {

    }

    }

    /** Transform an awaitable before co_await.

    /** Transform an awaitable before co_await.

        Override this in your derived promise type to customize how

        Override this in your derived promise type to customize how

        awaitables are transformed. The default implementation passes

        awaitables are transformed. The default implementation passes

        the awaitable through unchanged.

        the awaitable through unchanged.

        @param a The awaitable expression from `co_await a`.

        @param a The awaitable expression from `co_await a`.

        @return The transformed awaitable.

        @return The transformed awaitable.

    */

    */

    template<typename A>

    template<typename A>

    decltype(auto) transform_awaitable(A&& a)

    decltype(auto) transform_awaitable(A&& a)

    {

    {

        return std::forward<A>(a);

        return std::forward<A>(a);

    }

    }

    /** Intercept co_await expressions.

    /** Intercept co_await expressions.

        This function handles @ref this_coro::environment_tag and

        This function handles @ref this_coro::environment_tag and

        the fine-grained tags (@ref this_coro::executor_tag,

        the fine-grained tags (@ref this_coro::executor_tag,

        @ref this_coro::stop_token_tag, @ref this_coro::frame_allocator_tag)

        @ref this_coro::stop_token_tag, @ref this_coro::frame_allocator_tag)

        specially, returning an awaiter that yields the stored value.

        specially, returning an awaiter that yields the stored value.

        All other awaitables are delegated to @ref transform_awaitable.

        All other awaitables are delegated to @ref transform_awaitable.

        @param t The awaited expression.

        @param t The awaited expression.

        @return An awaiter for the expression.

        @return An awaiter for the expression.

    */

    */

    template<typename T>

    template<typename T>

    {

    {

        using Tag = std::decay_t<T>;

        using Tag = std::decay_t<T>;

        if constexpr (std::is_same_v<Tag, this_coro::environment_tag>)

        if constexpr (std::is_same_v<Tag, this_coro::environment_tag>)

        {

        {

            struct awaiter

            struct awaiter

            {

            {

                io_env const* env_;

                io_env const* env_;

            };

            };

        }

        }

        else if constexpr (std::is_same_v<Tag, this_coro::executor_tag>)

        else if constexpr (std::is_same_v<Tag, this_coro::executor_tag>)

        {

        {

            struct awaiter

            struct awaiter

            {

            {

                executor_ref executor_;

                executor_ref executor_;

                void await_suspend(std::coroutine_handle<>) const noexcept { }

                void await_suspend(std::coroutine_handle<>) const noexcept { }

            };

            };

        }

        }

        else if constexpr (std::is_same_v<Tag, this_coro::stop_token_tag>)

        else if constexpr (std::is_same_v<Tag, this_coro::stop_token_tag>)

        {

        {

            struct awaiter

            struct awaiter

            {

            {

                std::stop_token token_;

                std::stop_token token_;

            };

            };

        }

        }

        else if constexpr (std::is_same_v<Tag, this_coro::frame_allocator_tag>)

        else if constexpr (std::is_same_v<Tag, this_coro::frame_allocator_tag>)

        {

        {

            struct awaiter

            struct awaiter

            {

            {

                std::pmr::memory_resource* frame_allocator_;

                std::pmr::memory_resource* frame_allocator_;

            };

            };

        }

        }

        else

        else

        {

        {

        }

        }

    }

    }

};

};

} // namespace capy

} // namespace capy

} // namespace boost

} // namespace boost

#endif

#endif