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_TEST_RUN_BLOCKING_HPP

#ifndef BOOST_CAPY_TEST_RUN_BLOCKING_HPP

#define BOOST_CAPY_TEST_RUN_BLOCKING_HPP

#define BOOST_CAPY_TEST_RUN_BLOCKING_HPP

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

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

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

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

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

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

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

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

#include <coroutine>

#include <coroutine>

#include <exception>

#include <exception>

#include <stop_token>

#include <stop_token>

#include <type_traits>

#include <type_traits>

#include <utility>

#include <utility>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

namespace test {

namespace test {

class blocking_context;

class blocking_context;

/** Single-threaded executor for blocking synchronous tests.

/** Single-threaded executor for blocking synchronous tests.

    This executor is used internally by @ref run_blocking to

    This executor is used internally by @ref run_blocking to

    execute coroutine tasks on the calling thread. Work submitted

    execute coroutine tasks on the calling thread. Work submitted

    via `dispatch()` is returned for symmetric transfer. Work

    via `dispatch()` is returned for symmetric transfer. Work

    submitted via `post()` is enqueued and processed by the

    submitted via `post()` is enqueued and processed by the

    @ref blocking_context event loop.

    @ref blocking_context event loop.

    Users do not construct this type directly. It is obtained

    Users do not construct this type directly. It is obtained

    from @ref blocking_context::get_executor.

    from @ref blocking_context::get_executor.

    @par Thread Safety

    @par Thread Safety

    All member functions are safe to call from any thread.

    All member functions are safe to call from any thread.

    @see blocking_context, run_blocking

    @see blocking_context, run_blocking

*/

*/

struct BOOST_CAPY_DECL blocking_executor

struct BOOST_CAPY_DECL blocking_executor

{

{

    /// Construct from a context pointer.

    /// Construct from a context pointer.

        blocking_context* ctx) noexcept

        blocking_context* ctx) noexcept

    {

    {

    /** Compare two blocking executors for equality.

    /** Compare two blocking executors for equality.

        Two executors are equal if they share the same context.

        Two executors are equal if they share the same context.

    */

    */

    bool

    bool

    operator==(blocking_executor const& other) const noexcept;

    operator==(blocking_executor const& other) const noexcept;

    /** Return the associated execution context.

    /** Return the associated execution context.

        @return A reference to the owning `blocking_context`.

        @return A reference to the owning `blocking_context`.

    */

    */

    blocking_context&

    blocking_context&

    context() const noexcept;

    context() const noexcept;

    /// Called when work is submitted (no-op).

    /// Called when work is submitted (no-op).

    void on_work_started() const noexcept;

    void on_work_started() const noexcept;

    /// Called when work completes (no-op).

    /// Called when work completes (no-op).

    void on_work_finished() const noexcept;

    void on_work_finished() const noexcept;

    /** Dispatch work for immediate inline execution.

    /** Dispatch work for immediate inline execution.

        Returns the handle for symmetric transfer. The caller

        Returns the handle for symmetric transfer. The caller

        resumes the coroutine via the returned handle.

        resumes the coroutine via the returned handle.

        @param h The coroutine handle to execute.

        @param h The coroutine handle to execute.

        @return `h` for symmetric transfer.

        @return `h` for symmetric transfer.

    */

    */

    std::coroutine_handle<>

    std::coroutine_handle<>

    dispatch(std::coroutine_handle<> h) const;

    dispatch(std::coroutine_handle<> h) const;

    /** Post work for deferred execution.

    /** Post work for deferred execution.

        Enqueues the coroutine handle into the context's work

        Enqueues the coroutine handle into the context's work

        queue. The handle is resumed when the blocking event

        queue. The handle is resumed when the blocking event

        loop processes it.

        loop processes it.

        @param h The coroutine handle to enqueue.

        @param h The coroutine handle to enqueue.

    */

    */

    void

    void

    post(std::coroutine_handle<> h) const;

    post(std::coroutine_handle<> h) const;

private:

private:

    blocking_context* ctx_;

    blocking_context* ctx_;

};

};

/** Single-threaded execution context for blocking tests.

/** Single-threaded execution context for blocking tests.

    Provides a work queue and event loop that runs on the

    Provides a work queue and event loop that runs on the

    calling thread. Coroutines dispatched through the

    calling thread. Coroutines dispatched through the

    associated @ref blocking_executor have their `post()`

    associated @ref blocking_executor have their `post()`

    calls enqueued and processed by @ref run, which blocks

    calls enqueued and processed by @ref run, which blocks

    until @ref signal_done is called.

    until @ref signal_done is called.

    This context is created internally by @ref run_blocking.

    This context is created internally by @ref run_blocking.

    Users do not interact with it directly.

    Users do not interact with it directly.

    @par Thread Safety

    @par Thread Safety

    The event loop runs on the thread that calls `run()`.

    The event loop runs on the thread that calls `run()`.

    `signal_done()` and `enqueue()` are safe to call from

    `signal_done()` and `enqueue()` are safe to call from

    any thread.

    any thread.

    @see blocking_executor, run_blocking

    @see blocking_executor, run_blocking

*/

*/

class BOOST_CAPY_DECL blocking_context

class BOOST_CAPY_DECL blocking_context

    : public execution_context

    : public execution_context

{

{

    struct impl;

    struct impl;

    impl* impl_;

    impl* impl_;

public:

public:

    using executor_type = blocking_executor;

    using executor_type = blocking_executor;

    /** Construct a blocking context.

    /** Construct a blocking context.

        Allocates the internal work queue and

        Allocates the internal work queue and

        synchronization state.

        synchronization state.

    */

    */

    blocking_context();

    blocking_context();

    /** Destroy the blocking context. */

    /** Destroy the blocking context. */

    ~blocking_context();

    ~blocking_context();

    /** Return an executor bound to this context.

    /** Return an executor bound to this context.

        @return A `blocking_executor` that enqueues work

        @return A `blocking_executor` that enqueues work

            into this context's queue.

            into this context's queue.

    */

    */

    blocking_executor

    blocking_executor

    get_executor() noexcept;

    get_executor() noexcept;

    /** Signal that the task has completed.

    /** Signal that the task has completed.

        Wakes the event loop so that @ref run returns.

        Wakes the event loop so that @ref run returns.

    */

    */

    void

    void

    signal_done() noexcept;

    signal_done() noexcept;

    /** Signal that the task has completed with an error.

    /** Signal that the task has completed with an error.

        Stores the exception and wakes the event loop

        Stores the exception and wakes the event loop

        so that @ref run rethrows it.

        so that @ref run rethrows it.

        @param ep The exception to propagate.

        @param ep The exception to propagate.

    */

    */

    void

    void

    signal_done(std::exception_ptr ep) noexcept;

    signal_done(std::exception_ptr ep) noexcept;

    /** Run the event loop until done.

    /** Run the event loop until done.

        Blocks the calling thread, processing posted

        Blocks the calling thread, processing posted

        coroutine handles until @ref signal_done is called.

        coroutine handles until @ref signal_done is called.

        After draining remaining work, rethrows any stored

        After draining remaining work, rethrows any stored

        exception.

        exception.

        @par Exception Safety

        @par Exception Safety

        Basic guarantee. If the completed task stored an

        Basic guarantee. If the completed task stored an

        exception via `signal_done(ep)`, it is rethrown.

        exception via `signal_done(ep)`, it is rethrown.

    */

    */

    void

    void

    run();

    run();

    /** Enqueue a coroutine handle for processing.

    /** Enqueue a coroutine handle for processing.

        @param h The coroutine handle to enqueue.

        @param h The coroutine handle to enqueue.

    */

    */

    void

    void

    enqueue(std::coroutine_handle<> h);

    enqueue(std::coroutine_handle<> h);

};

};

/** Wrapper that signals completion after invoking the handler.

/** Wrapper that signals completion after invoking the handler.

    Forwards invocations to the contained handler_pair, then

    Forwards invocations to the contained handler_pair, then

    signals the `blocking_context` so that its event loop

    signals the `blocking_context` so that its event loop

    unblocks. Exceptions thrown by the handler are captured

    unblocks. Exceptions thrown by the handler are captured

    and stored for later rethrow.

    and stored for later rethrow.

    @tparam H1 The success handler type.

    @tparam H1 The success handler type.

    @tparam H2 The error handler type.

    @tparam H2 The error handler type.

    @par Thread Safety

    @par Thread Safety

    Safe to invoke from any thread.

    Safe to invoke from any thread.

    @see run_blocking, blocking_context

    @see run_blocking, blocking_context

*/

*/

template<class H1, class H2>

template<class H1, class H2>

struct blocking_handler_wrapper

struct blocking_handler_wrapper

{

{

    blocking_context* ctx_;

    blocking_context* ctx_;

    detail::handler_pair<H1, H2> handlers_;

    detail::handler_pair<H1, H2> handlers_;

    /** Invoke the handler with a non-void result. */

    /** Invoke the handler with a non-void result. */

    template<class T>

    template<class T>

    {

    {

        try

        try

        {

        {

        }

        }

        catch(...)

        catch(...)

        {

        {

            ctx_->signal_done(std::current_exception());

            ctx_->signal_done(std::current_exception());

            return;

            return;

        }

        }

    }

    }

    /** Invoke the handler for a void result. */

    /** Invoke the handler for a void result. */

    {

    {

        try

        try

        {

        {

        }

        }

        catch(...)

        catch(...)

        {

        {

            ctx_->signal_done(std::current_exception());

            ctx_->signal_done(std::current_exception());

            return;

            return;

        }

        }

    }

    }

    /** Invoke the handler with an exception. */

    /** Invoke the handler with an exception. */

    {

    {

        try

        try

        {

        {

        }

        }

        {

        {

        }

        }

    }

    }

};

};

/** Wrapper returned by run_blocking that accepts a task.

/** Wrapper returned by run_blocking that accepts a task.

    Holds the handlers and optional stop token. When invoked

    Holds the handlers and optional stop token. When invoked

    with a task, creates a @ref blocking_context, launches

    with a task, creates a @ref blocking_context, launches

    the task via `run_async`, and pumps the event loop until

    the task via `run_async`, and pumps the event loop until

    the task completes.

    the task completes.

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

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

    wrapper can only be used as a temporary.

    wrapper can only be used as a temporary.

    @tparam H1 The success handler type.

    @tparam H1 The success handler type.

    @tparam H2 The error handler type.

    @tparam H2 The error handler type.

    @par Thread Safety

    @par Thread Safety

    The wrapper itself should only be used from one thread.

    The wrapper itself should only be used from one thread.

    The calling thread blocks until the task completes.

    The calling thread blocks until the task completes.

    @par Example

    @par Example

    @code

    @code

    int result = 0;

    int result = 0;

    run_blocking([&](int v) { result = v; })(my_task());

    run_blocking([&](int v) { result = v; })(my_task());

    @endcode

    @endcode

    @see run_blocking, run_async

    @see run_blocking, run_async

*/

*/

template<class H1, class H2>

template<class H1, class H2>

class [[nodiscard]] run_blocking_wrapper

class [[nodiscard]] run_blocking_wrapper

{

{

    std::stop_token st_;

    std::stop_token st_;

    H1 h1_;

    H1 h1_;

    H2 h2_;

    H2 h2_;

public:

public:

    /** Construct wrapper with stop token and handlers.

    /** Construct wrapper with stop token and handlers.

        @param st The stop token for cooperative cancellation.

        @param st The stop token for cooperative cancellation.

        @param h1 The success handler.

        @param h1 The success handler.

        @param h2 The error handler.

        @param h2 The error handler.

    */

    */

        std::stop_token st,

        std::stop_token st,

        H1 h1,

        H1 h1,

        H2 h2)

        H2 h2)

    {

    {

    run_blocking_wrapper(run_blocking_wrapper const&) = delete;

    run_blocking_wrapper(run_blocking_wrapper const&) = delete;

    run_blocking_wrapper(run_blocking_wrapper&&) = delete;

    run_blocking_wrapper(run_blocking_wrapper&&) = delete;

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

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

    run_blocking_wrapper& operator=(run_blocking_wrapper&&) = delete;

    run_blocking_wrapper& operator=(run_blocking_wrapper&&) = delete;

    /** Launch the task and block until completion.

    /** Launch the task and block until completion.

        Creates a blocking_context with a single-threaded

        Creates a blocking_context with a single-threaded

        event loop, launches the task via `run_async`, then

        event loop, launches the task via `run_async`, then

        pumps the loop until the task completes or throws.

        pumps the loop until the task completes or throws.

        @tparam Task The IoRunnable type.

        @tparam Task The IoRunnable type.

        @param t The task to execute.

        @param t The task to execute.

    */

    */

    template<IoRunnable Task>

    template<IoRunnable Task>

    void

    void

    {

    {

            if constexpr(

            if constexpr(

                std::is_same_v<H2, detail::default_handler>)

                std::is_same_v<H2, detail::default_handler>)

                return detail::handler_pair<H1, H2>{

                return detail::handler_pair<H1, H2>{

            else

            else

                return detail::handler_pair<H1, H2>{

                return detail::handler_pair<H1, H2>{

        };

        };

        run_async(

        run_async(

            ctx.get_executor(),

            ctx.get_executor(),

            blocking_handler_wrapper<H1, H2>{

            blocking_handler_wrapper<H1, H2>{

};

};

/** Block until task completes and discard result.

/** Block until task completes and discard result.

    Executes a lazy task on a single-threaded event loop

    Executes a lazy task on a single-threaded event loop

    and blocks the calling thread until the task completes

    and blocks the calling thread until the task completes

    or throws.

    or throws.

    @par Exception Safety

    @par Exception Safety

    Basic guarantee. If the task throws, the exception is

    Basic guarantee. If the task throws, the exception is

    rethrown to the caller.

    rethrown to the caller.

    @par Example

    @par Example

    @code

    @code

    run_blocking()(my_void_task());

    run_blocking()(my_void_task());

    @endcode

    @endcode

    @return A wrapper that accepts a task for blocking execution.

    @return A wrapper that accepts a task for blocking execution.

    @see run_async

    @see run_async

*/

*/

[[nodiscard]] inline auto

[[nodiscard]] inline auto

{

{

    return run_blocking_wrapper<

    return run_blocking_wrapper<

        detail::default_handler,

        detail::default_handler,

        detail::default_handler>(

        detail::default_handler>(

            detail::default_handler{},

            detail::default_handler{},

}

}

/** Block until task completes and invoke handler with result.

/** Block until task completes and invoke handler with result.

    Executes a lazy task on a single-threaded event loop

    Executes a lazy task on a single-threaded event loop

    and blocks until completion. The handler `h1` is called

    and blocks until completion. The handler `h1` is called

    with the result on success. If `h1` is also invocable

    with the result on success. If `h1` is also invocable

    with `std::exception_ptr`, it handles exceptions too.

    with `std::exception_ptr`, it handles exceptions too.

    Otherwise, exceptions are rethrown.

    Otherwise, exceptions are rethrown.

    @par Exception Safety

    @par Exception Safety

    Basic guarantee. Exceptions from the task are passed

    Basic guarantee. Exceptions from the task are passed

    to `h1` if it accepts `std::exception_ptr`, otherwise

    to `h1` if it accepts `std::exception_ptr`, otherwise

    rethrown.

    rethrown.

    @par Example

    @par Example

    @code

    @code

    int result = 0;

    int result = 0;

    run_blocking([&](int v) { result = v; })(compute());

    run_blocking([&](int v) { result = v; })(compute());

    @endcode

    @endcode

    @param h1 Handler invoked with the result on success,

    @param h1 Handler invoked with the result on success,

        and optionally with `std::exception_ptr` on failure.

        and optionally with `std::exception_ptr` on failure.

    @return A wrapper that accepts a task for blocking execution.

    @return A wrapper that accepts a task for blocking execution.

    @see run_async

    @see run_async

*/

*/

template<class H1>

template<class H1>

[[nodiscard]] auto

[[nodiscard]] auto

{

{

    return run_blocking_wrapper<

    return run_blocking_wrapper<

        H1,

        H1,

        detail::default_handler>(

        detail::default_handler>(

}

}

/** Block until task completes with separate handlers.

/** Block until task completes with separate handlers.

    Executes a lazy task on a single-threaded event loop

    Executes a lazy task on a single-threaded event loop

    and blocks until completion. The handler `h1` is called

    and blocks until completion. The handler `h1` is called

    on success, `h2` on failure.

    on success, `h2` on failure.

    @par Exception Safety

    @par Exception Safety

    Basic guarantee. Exceptions from the task are passed

    Basic guarantee. Exceptions from the task are passed

    to `h2`.

    to `h2`.

    @par Example

    @par Example

    @code

    @code

    int result = 0;

    int result = 0;

    run_blocking(

    run_blocking(

        [&](int v) { result = v; },

        [&](int v) { result = v; },

        [](std::exception_ptr ep) {

        [](std::exception_ptr ep) {

            std::rethrow_exception(ep);

            std::rethrow_exception(ep);

        }

        }

    )(compute());

    )(compute());

    @endcode

    @endcode

    @param h1 Handler invoked with the result on success.

    @param h1 Handler invoked with the result on success.

    @param h2 Handler invoked with the exception on failure.

    @param h2 Handler invoked with the exception on failure.

    @return A wrapper that accepts a task for blocking execution.

    @return A wrapper that accepts a task for blocking execution.

    @see run_async

    @see run_async

*/

*/

template<class H1, class H2>

template<class H1, class H2>

[[nodiscard]] auto

[[nodiscard]] auto

{

{

    return run_blocking_wrapper<

    return run_blocking_wrapper<

        H1,

        H1,

        H2>(

        H2>(

}

}

/** Block until task completes with stop token support.

/** Block until task completes with stop token support.

    Executes a lazy task on a single-threaded event loop

    Executes a lazy task on a single-threaded event loop

    with the given stop token and blocks until completion.

    with the given stop token and blocks until completion.

    @par Exception Safety

    @par Exception Safety

    Basic guarantee. If the task throws, the exception is

    Basic guarantee. If the task throws, the exception is

    rethrown to the caller.

    rethrown to the caller.

    @param st The stop token for cooperative cancellation.

    @param st The stop token for cooperative cancellation.

    @return A wrapper that accepts a task for blocking execution.

    @return A wrapper that accepts a task for blocking execution.

    @see run_async

    @see run_async

*/

*/

[[nodiscard]] inline auto

[[nodiscard]] inline auto

run_blocking(std::stop_token st)

run_blocking(std::stop_token st)

{

{

    return run_blocking_wrapper<

    return run_blocking_wrapper<

        detail::default_handler,

        detail::default_handler,

        detail::default_handler>(

        detail::default_handler>(

            std::move(st),

            std::move(st),

            detail::default_handler{},

            detail::default_handler{},

            detail::default_handler{});

            detail::default_handler{});

}

}

/** Block until task completes with stop token and handler.

/** Block until task completes with stop token and handler.

    @param st The stop token for cooperative cancellation.

    @param st The stop token for cooperative cancellation.

    @param h1 Handler invoked with the result on success.

    @param h1 Handler invoked with the result on success.

    @return A wrapper that accepts a task for blocking execution.

    @return A wrapper that accepts a task for blocking execution.

    @see run_async

    @see run_async

*/

*/

template<class H1>

template<class H1>

[[nodiscard]] auto

[[nodiscard]] auto

{

{

    return run_blocking_wrapper<

    return run_blocking_wrapper<

        H1,

        H1,

        detail::default_handler>(

        detail::default_handler>(

}

}

/** Block until task completes with stop token and handlers.

/** Block until task completes with stop token and handlers.

    @param st The stop token for cooperative cancellation.

    @param st The stop token for cooperative cancellation.

    @param h1 Handler invoked with the result on success.

    @param h1 Handler invoked with the result on success.

    @param h2 Handler invoked with the exception on failure.

    @param h2 Handler invoked with the exception on failure.

    @return A wrapper that accepts a task for blocking execution.

    @return A wrapper that accepts a task for blocking execution.

    @see run_async

    @see run_async

*/

*/

template<class H1, class H2>

template<class H1, class H2>

[[nodiscard]] auto

[[nodiscard]] auto

run_blocking(std::stop_token st, H1 h1, H2 h2)

run_blocking(std::stop_token st, H1 h1, H2 h2)

{

{

    return run_blocking_wrapper<

    return run_blocking_wrapper<

        H1,

        H1,

        H2>(

        H2>(

            std::move(st),

            std::move(st),

            std::move(h1),

            std::move(h1),

            std::move(h2));

            std::move(h2));

}

}

} // namespace test

} // namespace test

} // namespace capy

} // namespace capy

} // namespace boost

} // namespace boost

#endif

#endif