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_RUN_ASYNC_HPP

#ifndef BOOST_CAPY_RUN_ASYNC_HPP

#define BOOST_CAPY_RUN_ASYNC_HPP

#define BOOST_CAPY_RUN_ASYNC_HPP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#include <algorithm>

#include <algorithm>

#include <coroutine>

#include <coroutine>

#include <cstring>

#include <cstring>

#include <memory_resource>

#include <memory_resource>

#include <new>

#include <new>

#include <stop_token>

#include <stop_token>

#include <type_traits>

#include <type_traits>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

namespace detail {

namespace detail {

/// Function pointer type for type-erased frame deallocation.

/// Function pointer type for type-erased frame deallocation.

using dealloc_fn = void(*)(void*, std::size_t);

using dealloc_fn = void(*)(void*, std::size_t);

/// Type-erased deallocator implementation for trampoline frames.

/// Type-erased deallocator implementation for trampoline frames.

template<class Alloc>

template<class Alloc>

void dealloc_impl(void* raw, std::size_t total)

void dealloc_impl(void* raw, std::size_t total)

{

{

    static_assert(std::is_same_v<typename Alloc::value_type, std::byte>);

    static_assert(std::is_same_v<typename Alloc::value_type, std::byte>);

    auto* a = std::launder(reinterpret_cast<Alloc*>(

    auto* a = std::launder(reinterpret_cast<Alloc*>(

        static_cast<char*>(raw) + total - sizeof(Alloc)));

        static_cast<char*>(raw) + total - sizeof(Alloc)));

    Alloc ba(std::move(*a));

    Alloc ba(std::move(*a));

    a->~Alloc();

    a->~Alloc();

    ba.deallocate(static_cast<std::byte*>(raw), total);

    ba.deallocate(static_cast<std::byte*>(raw), total);

}

}

/// Awaiter to access the promise from within the coroutine.

/// Awaiter to access the promise from within the coroutine.

template<class Promise>

template<class Promise>

struct get_promise_awaiter

struct get_promise_awaiter

{

{

    Promise* p_ = nullptr;

    Promise* p_ = nullptr;

    {

    {

    }

    }

    {

    {

    }

    }

};

};

/** Internal run_async_trampoline coroutine for run_async.

/** Internal run_async_trampoline coroutine for run_async.

    The run_async_trampoline is allocated BEFORE the task (via C++17 postfix evaluation

    The run_async_trampoline is allocated BEFORE the task (via C++17 postfix evaluation

    order) and serves as the task's continuation. When the task final_suspends,

    order) and serves as the task's continuation. When the task final_suspends,

    control returns to the run_async_trampoline which then invokes the appropriate handler.

    control returns to the run_async_trampoline which then invokes the appropriate handler.

    For value-type allocators, the run_async_trampoline stores a frame_memory_resource

    For value-type allocators, the run_async_trampoline stores a frame_memory_resource

    that wraps the allocator. For memory_resource*, it stores the pointer directly.

    that wraps the allocator. For memory_resource*, it stores the pointer directly.

    @tparam Ex The executor type.

    @tparam Ex The executor type.

    @tparam Handlers The handler type (default_handler or handler_pair).

    @tparam Handlers The handler type (default_handler or handler_pair).

    @tparam Alloc The allocator type (value type or memory_resource*).

    @tparam Alloc The allocator type (value type or memory_resource*).

*/

*/

template<class Ex, class Handlers, class Alloc>

template<class Ex, class Handlers, class Alloc>

struct run_async_trampoline

struct run_async_trampoline

{

{

    using invoke_fn = void(*)(void*, Handlers&);

    using invoke_fn = void(*)(void*, Handlers&);

    struct promise_type

    struct promise_type

    {

    {

        work_guard<Ex> wg_;

        work_guard<Ex> wg_;

        Handlers handlers_;

        Handlers handlers_;

        frame_memory_resource<Alloc> resource_;

        frame_memory_resource<Alloc> resource_;

        io_env env_;

        io_env env_;

        invoke_fn invoke_ = nullptr;

        invoke_fn invoke_ = nullptr;

        void* task_promise_ = nullptr;

        void* task_promise_ = nullptr;

        std::coroutine_handle<> task_h_;

        std::coroutine_handle<> task_h_;

        promise_type(Ex& ex, Handlers& h, Alloc& a) noexcept

        promise_type(Ex& ex, Handlers& h, Alloc& a) noexcept

            : wg_(std::move(ex))

            : wg_(std::move(ex))

            , handlers_(std::move(h))

            , handlers_(std::move(h))

            , resource_(std::move(a))

            , resource_(std::move(a))

        {

        {

        }

        }

        static void* operator new(

        static void* operator new(

            std::size_t size, Ex const&, Handlers const&, Alloc a)

            std::size_t size, Ex const&, Handlers const&, Alloc a)

        {

        {

            using byte_alloc = typename std::allocator_traits<Alloc>

            using byte_alloc = typename std::allocator_traits<Alloc>

                ::template rebind_alloc<std::byte>;

                ::template rebind_alloc<std::byte>;

            constexpr auto footer_align =

            constexpr auto footer_align =

                (std::max)(alignof(dealloc_fn), alignof(Alloc));

                (std::max)(alignof(dealloc_fn), alignof(Alloc));

            auto padded = (size + footer_align - 1) & ~(footer_align - 1);

            auto padded = (size + footer_align - 1) & ~(footer_align - 1);

            auto total = padded + sizeof(dealloc_fn) + sizeof(Alloc);

            auto total = padded + sizeof(dealloc_fn) + sizeof(Alloc);

            byte_alloc ba(std::move(a));

            byte_alloc ba(std::move(a));

            void* raw = ba.allocate(total);

            void* raw = ba.allocate(total);

            auto* fn_loc = reinterpret_cast<dealloc_fn*>(

            auto* fn_loc = reinterpret_cast<dealloc_fn*>(

                static_cast<char*>(raw) + padded);

                static_cast<char*>(raw) + padded);

            *fn_loc = &dealloc_impl<byte_alloc>;

            *fn_loc = &dealloc_impl<byte_alloc>;

            new (fn_loc + 1) byte_alloc(std::move(ba));

            new (fn_loc + 1) byte_alloc(std::move(ba));

            return raw;

            return raw;

        }

        }

        {

        {

                (std::max)(alignof(dealloc_fn), alignof(Alloc));

                (std::max)(alignof(dealloc_fn), alignof(Alloc));

                static_cast<char*>(ptr) + padded);

                static_cast<char*>(ptr) + padded);

        std::pmr::memory_resource* get_resource() noexcept

        std::pmr::memory_resource* get_resource() noexcept

        {

        {

            return &resource_;

            return &resource_;

        }

        }

        run_async_trampoline get_return_object() noexcept

        run_async_trampoline get_return_object() noexcept

        {

        {

            return run_async_trampoline{

            return run_async_trampoline{

                std::coroutine_handle<promise_type>::from_promise(*this)};

                std::coroutine_handle<promise_type>::from_promise(*this)};

        }

        }

        {

        {

        }

        }

        {

        {

            // MSVC <= 19.39 misallocates the await_suspend return buffer

            // inside the coroutine frame; destroying the frame from

            // await_suspend then causes use-after-free. A void-returning

            // await_suspend avoids the problem. See:

            // https://developercommunity.visualstudio.com/t/destroy-coroutine-from-final_suspend-r/10096047

            struct destroyer

            {

                    std::coroutine_handle<> h) noexcept

                {

            };

        }

        }

        {

        {

        {

        {

    };

    };

    std::coroutine_handle<promise_type> h_;

    std::coroutine_handle<promise_type> h_;

    template<IoRunnable Task>

    template<IoRunnable Task>

    static void invoke_impl(void* p, Handlers& h)

    static void invoke_impl(void* p, Handlers& h)

    {

    {

        using R = decltype(std::declval<Task&>().await_resume());

        using R = decltype(std::declval<Task&>().await_resume());

        auto& promise = *static_cast<typename Task::promise_type*>(p);

        auto& promise = *static_cast<typename Task::promise_type*>(p);

        if(promise.exception())

        if(promise.exception())

            h(promise.exception());

            h(promise.exception());

        else if constexpr(std::is_void_v<R>)

        else if constexpr(std::is_void_v<R>)

            h();

            h();

        else

        else

            h(std::move(promise.result()));

            h(std::move(promise.result()));

    }

    }

};

};

/** Specialization for memory_resource* - stores pointer directly.

/** Specialization for memory_resource* - stores pointer directly.

    This avoids double indirection when the user passes a memory_resource*.

    This avoids double indirection when the user passes a memory_resource*.

*/

*/

template<class Ex, class Handlers>

template<class Ex, class Handlers>

struct run_async_trampoline<Ex, Handlers, std::pmr::memory_resource*>

struct run_async_trampoline<Ex, Handlers, std::pmr::memory_resource*>

{

{

    using invoke_fn = void(*)(void*, Handlers&);

    using invoke_fn = void(*)(void*, Handlers&);

    struct promise_type

    struct promise_type

    {

    {

        work_guard<Ex> wg_;

        work_guard<Ex> wg_;

        Handlers handlers_;

        Handlers handlers_;

        std::pmr::memory_resource* mr_;

        std::pmr::memory_resource* mr_;

        io_env env_;

        io_env env_;

        invoke_fn invoke_ = nullptr;

        invoke_fn invoke_ = nullptr;

        void* task_promise_ = nullptr;

        void* task_promise_ = nullptr;

        std::coroutine_handle<> task_h_;

        std::coroutine_handle<> task_h_;

            Ex& ex, Handlers& h, std::pmr::memory_resource* mr) noexcept

            Ex& ex, Handlers& h, std::pmr::memory_resource* mr) noexcept

        {

        {

            std::size_t size, Ex const&, Handlers const&,

            std::size_t size, Ex const&, Handlers const&,

            std::pmr::memory_resource* mr)

            std::pmr::memory_resource* mr)

        {

        {

        }

        }

        {

        {

            std::pmr::memory_resource* mr;

            std::pmr::memory_resource* mr;

        {

        {

        }

        }

        {

        {

            return run_async_trampoline{

            return run_async_trampoline{

        }

        }

        {

        {

        }

        }

        {

        {

            // MSVC <= 19.39 misallocates the await_suspend return buffer

            // inside the coroutine frame; destroying the frame from

            // await_suspend then causes use-after-free. A void-returning

            // await_suspend avoids the problem. See:

            // https://developercommunity.visualstudio.com/t/destroy-coroutine-from-final_suspend-r/10096047

            struct destroyer

            {

                    std::coroutine_handle<> h) noexcept

                {

            };

        }

        }

        {

        {

        {

        {

    };

    };

    std::coroutine_handle<promise_type> h_;

    std::coroutine_handle<promise_type> h_;

    template<IoRunnable Task>

    template<IoRunnable Task>

    {

    {

        using R = decltype(std::declval<Task&>().await_resume());

        using R = decltype(std::declval<Task&>().await_resume());

        else if constexpr(std::is_void_v<R>)

        else if constexpr(std::is_void_v<R>)

        else

        else

};

};

/// Coroutine body for run_async_trampoline - invokes handlers then destroys task.

/// Coroutine body for run_async_trampoline - invokes handlers then destroys task.

template<class Ex, class Handlers, class Alloc>

template<class Ex, class Handlers, class Alloc>

run_async_trampoline<Ex, Handlers, Alloc>

run_async_trampoline<Ex, Handlers, Alloc>

{

{

    // promise_type ctor steals the parameters

    // promise_type ctor steals the parameters

    auto& p = co_await get_promise_awaiter<

    auto& p = co_await get_promise_awaiter<

        typename run_async_trampoline<Ex, Handlers, Alloc>::promise_type>{};

        typename run_async_trampoline<Ex, Handlers, Alloc>::promise_type>{};

    p.invoke_(p.task_promise_, p.handlers_);

    p.invoke_(p.task_promise_, p.handlers_);

    p.task_h_.destroy();

    p.task_h_.destroy();

} // namespace detail

} // namespace detail

/** Wrapper returned by run_async that accepts a task for execution.

/** Wrapper returned by run_async that accepts a task for execution.

    This wrapper holds the run_async_trampoline coroutine, executor, stop token,

    This wrapper holds the run_async_trampoline coroutine, executor, stop token,

    and handlers. The run_async_trampoline is allocated when the wrapper is constructed

    and handlers. The run_async_trampoline is allocated when the wrapper is constructed

    (before the task due to C++17 postfix evaluation order).

    (before the task due to C++17 postfix evaluation order).

    The rvalue ref-qualifier on `operator()` ensures the wrapper can only

    The rvalue ref-qualifier on `operator()` ensures the wrapper can only

    be used as a temporary, preventing misuse that would violate LIFO ordering.

    be used as a temporary, preventing misuse that would violate LIFO ordering.

    @tparam Ex The executor type satisfying the `Executor` concept.

    @tparam Ex The executor type satisfying the `Executor` concept.

    @tparam Handlers The handler type (default_handler or handler_pair).

    @tparam Handlers The handler type (default_handler or handler_pair).

    @tparam Alloc The allocator type (value type or memory_resource*).

    @tparam Alloc The allocator type (value type or memory_resource*).

    @par Thread Safety

    @par Thread Safety

    The wrapper itself should only be used from one thread. The handlers

    The wrapper itself should only be used from one thread. The handlers

    may be invoked from any thread where the executor schedules work.

    may be invoked from any thread where the executor schedules work.

    @par Example

    @par Example

    @code

    @code

    // Correct usage - wrapper is temporary

    // Correct usage - wrapper is temporary

    run_async(ex)(my_task());

    run_async(ex)(my_task());

    // Compile error - cannot call operator() on lvalue

    // Compile error - cannot call operator() on lvalue

    auto w = run_async(ex);

    auto w = run_async(ex);

    w(my_task());  // Error: operator() requires rvalue

    w(my_task());  // Error: operator() requires rvalue

    @endcode

    @endcode

    @see run_async

    @see run_async

*/

*/

template<Executor Ex, class Handlers, class Alloc>

template<Executor Ex, class Handlers, class Alloc>

class [[nodiscard]] run_async_wrapper

class [[nodiscard]] run_async_wrapper

{

{

    detail::run_async_trampoline<Ex, Handlers, Alloc> tr_;

    detail::run_async_trampoline<Ex, Handlers, Alloc> tr_;

    std::stop_token st_;

    std::stop_token st_;

    std::pmr::memory_resource* saved_tls_;

    std::pmr::memory_resource* saved_tls_;

public:

public:

    /// Construct wrapper with executor, stop token, handlers, and allocator.

    /// Construct wrapper with executor, stop token, handlers, and allocator.

        Ex ex,

        Ex ex,

        std::stop_token st,

        std::stop_token st,

        Handlers h,

        Handlers h,

        Alloc a) noexcept

        Alloc a) noexcept

    {

    {

        if constexpr (!std::is_same_v<Alloc, std::pmr::memory_resource*>)

        if constexpr (!std::is_same_v<Alloc, std::pmr::memory_resource*>)

        {

        {

            static_assert(

            static_assert(

                std::is_nothrow_move_constructible_v<Alloc>,

                std::is_nothrow_move_constructible_v<Alloc>,

                "Allocator must be nothrow move constructible");

                "Allocator must be nothrow move constructible");

        }

        }

        // Set TLS before task argument is evaluated

        // Set TLS before task argument is evaluated

    {

    {

        // Restore TLS so stale pointer doesn't outlive

        // Restore TLS so stale pointer doesn't outlive

        // the execution context that owns the resource.

        // the execution context that owns the resource.

    // Non-copyable, non-movable (must be used immediately)

    // Non-copyable, non-movable (must be used immediately)

    run_async_wrapper(run_async_wrapper const&) = delete;

    run_async_wrapper(run_async_wrapper const&) = delete;

    run_async_wrapper(run_async_wrapper&&) = delete;

    run_async_wrapper(run_async_wrapper&&) = delete;

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

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

    run_async_wrapper& operator=(run_async_wrapper&&) = delete;

    run_async_wrapper& operator=(run_async_wrapper&&) = delete;

    /** Launch the task for execution.

    /** Launch the task for execution.

        This operator accepts a task and launches it on the executor.

        This operator accepts a task and launches it on the executor.

        The rvalue ref-qualifier ensures the wrapper is consumed, enforcing

        The rvalue ref-qualifier ensures the wrapper is consumed, enforcing

        correct LIFO destruction order.

        correct LIFO destruction order.

        The `io_env` constructed for the task is owned by the trampoline

        The `io_env` constructed for the task is owned by the trampoline

        coroutine and is guaranteed to outlive the task and all awaitables

        coroutine and is guaranteed to outlive the task and all awaitables

        in its chain. Awaitables may store `io_env const*` without concern

        in its chain. Awaitables may store `io_env const*` without concern

        for dangling references.

        for dangling references.

        @tparam Task The IoRunnable type.

        @tparam Task The IoRunnable type.

        @param t The task to execute. Ownership is transferred to the

        @param t The task to execute. Ownership is transferred to the

                 run_async_trampoline which will destroy it after completion.

                 run_async_trampoline which will destroy it after completion.

    */

    */

    template<IoRunnable Task>

    template<IoRunnable Task>

    {

    {

        // Inject Task-specific invoke function

        // Inject Task-specific invoke function

        // Setup task's continuation to return to run_async_trampoline

        // Setup task's continuation to return to run_async_trampoline

        // Start task through executor

        // Start task through executor

};

};

// Executor only (uses default recycling allocator)

// Executor only (uses default recycling allocator)

/** Asynchronously launch a lazy task on the given executor.

/** Asynchronously launch a lazy task on the given executor.

    Use this to start execution of a `task<T>` that was created lazily.

    Use this to start execution of a `task<T>` that was created lazily.

    The returned wrapper must be immediately invoked with the task;

    The returned wrapper must be immediately invoked with the task;

    storing the wrapper and calling it later violates LIFO ordering.

    storing the wrapper and calling it later violates LIFO ordering.

    Uses the default recycling frame allocator for coroutine frames.

    Uses the default recycling frame allocator for coroutine frames.

    With no handlers, the result is discarded and exceptions are rethrown.

    With no handlers, the result is discarded and exceptions are rethrown.

    @par Thread Safety

    @par Thread Safety

    The wrapper and handlers may be called from any thread where the

    The wrapper and handlers may be called from any thread where the

    executor schedules work.

    executor schedules work.

    @par Example

    @par Example

    @code

    @code

    run_async(ioc.get_executor())(my_task());

    run_async(ioc.get_executor())(my_task());

    @endcode

    @endcode

    @param ex The executor to execute the task on.

    @param ex The executor to execute the task on.

    @return A wrapper that accepts a `task<T>` for immediate execution.

    @return A wrapper that accepts a `task<T>` for immediate execution.

    @see task

    @see task

    @see executor

    @see executor

*/

*/

template<Executor Ex>

template<Executor Ex>

[[nodiscard]] auto

[[nodiscard]] auto

{

{

    return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(

    return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(

        detail::default_handler{},

        detail::default_handler{},

}

}

/** Asynchronously launch a lazy task with a result handler.

/** Asynchronously launch a lazy task with a result handler.

    The handler `h1` is called with the task's result on success. If `h1`

    The handler `h1` is called with the task's result on success. If `h1`

    is also invocable with `std::exception_ptr`, it handles exceptions too.

    is also invocable with `std::exception_ptr`, it handles exceptions too.

    Otherwise, exceptions are rethrown.

    Otherwise, exceptions are rethrown.

    @par Thread Safety

    @par Thread Safety

    The handler may be called from any thread where the executor

    The handler may be called from any thread where the executor

    schedules work.

    schedules work.

    @par Example

    @par Example

    @code

    @code

    // Handler for result only (exceptions rethrown)

    // Handler for result only (exceptions rethrown)

    run_async(ex, [](int result) {

    run_async(ex, [](int result) {

        std::cout << "Got: " << result << "\n";

        std::cout << "Got: " << result << "\n";

    })(compute_value());

    })(compute_value());

    // Overloaded handler for both result and exception

    // Overloaded handler for both result and exception

    run_async(ex, overloaded{

    run_async(ex, overloaded{

        [](int result) { std::cout << "Got: " << result << "\n"; },

        [](int result) { std::cout << "Got: " << result << "\n"; },

        [](std::exception_ptr) { std::cout << "Failed\n"; }

        [](std::exception_ptr) { std::cout << "Failed\n"; }

    })(compute_value());

    })(compute_value());

    @endcode

    @endcode

    @param ex The executor to execute the task on.

    @param ex The executor to execute the task on.

    @param h1 The handler to invoke with the result (and optionally exception).

    @param h1 The handler to invoke with the result (and optionally exception).

    @return A wrapper that accepts a `task<T>` for immediate execution.

    @return A wrapper that accepts a `task<T>` for immediate execution.

    @see task

    @see task

    @see executor

    @see executor

*/

*/

template<Executor Ex, class H1>

template<Executor Ex, class H1>

[[nodiscard]] auto

[[nodiscard]] auto

{

{

    return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(

    return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(

}

}

/** Asynchronously launch a lazy task with separate result and error handlers.

/** Asynchronously launch a lazy task with separate result and error handlers.

    The handler `h1` is called with the task's result on success.

    The handler `h1` is called with the task's result on success.

    The handler `h2` is called with the exception_ptr on failure.

    The handler `h2` is called with the exception_ptr on failure.

    @par Thread Safety

    @par Thread Safety

    The handlers may be called from any thread where the executor

    The handlers may be called from any thread where the executor

    schedules work.

    schedules work.

    @par Example

    @par Example

    @code

    @code

    run_async(ex,

    run_async(ex,

        [](int result) { std::cout << "Got: " << result << "\n"; },

        [](int result) { std::cout << "Got: " << result << "\n"; },

        [](std::exception_ptr ep) {

        [](std::exception_ptr ep) {

            try { std::rethrow_exception(ep); }

            try { std::rethrow_exception(ep); }

            catch (std::exception const& e) {

            catch (std::exception const& e) {

                std::cout << "Error: " << e.what() << "\n";

                std::cout << "Error: " << e.what() << "\n";