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_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/coro.hpp>

#include <boost/capy/coro.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 <boost/capy/ex/system_context.hpp>

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

#include <condition_variable>

#include <condition_variable>

#include <exception>

#include <exception>

#include <mutex>

#include <mutex>

#include <stdexcept>

#include <stdexcept>

#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 {

struct inline_executor;

struct inline_executor;

/** Execution context for inline blocking execution.

/** Execution context for inline blocking execution.

    This execution context is used with inline_executor for

    This execution context is used with inline_executor for

    blocking synchronous execution. It satisfies the

    blocking synchronous execution. It satisfies the

    ExecutionContext concept requirements.

    ExecutionContext concept requirements.

    @see inline_executor

    @see inline_executor

    @see run_blocking

    @see run_blocking

*/

*/

class inline_context : public execution_context

class inline_context : public execution_context

{

{

public:

public:

    using executor_type = inline_executor;

    using executor_type = inline_executor;

    executor_type

    executor_type

    get_executor() noexcept;

    get_executor() noexcept;

};

};

/** Synchronous executor that executes inline and disallows posting.

/** Synchronous executor that executes inline and disallows posting.

    This executor executes work synchronously on the calling thread

    This executor executes work synchronously on the calling thread

    via `dispatch()`. Calling `post()` throws `std::logic_error`

    via `dispatch()`. Calling `post()` throws `std::logic_error`

    because posting implies deferred execution which is incompatible

    because posting implies deferred execution which is incompatible

    with blocking synchronous semantics.

    with blocking synchronous semantics.

    @par Thread Safety

    @par Thread Safety

    All member functions are thread-safe.

    All member functions are thread-safe.

    @see run_blocking

    @see run_blocking

*/

*/

struct inline_executor

struct inline_executor

{

{

    /// Compare two inline executors for equality.

    /// Compare two inline executors for equality.

    bool

    bool

    {

    {

    }

    }

    /** Return the associated execution context.

    /** Return the associated execution context.

        @return A reference to a function-local static `inline_context`.

        @return A reference to a function-local static `inline_context`.

    */

    */

    inline_context&

    inline_context&

    {

    {

    }

    }

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

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

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

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

    /** Dispatch work for immediate inline execution.

    /** Dispatch work for immediate inline execution.

        @param h The coroutine handle to execute.

        @param h The coroutine handle to execute.

    */

    */

    void

    void

    {

    {

    /** Post work for deferred execution.

    /** Post work for deferred execution.

        @par Exception Safety

        @par Exception Safety

        Always throws.

        Always throws.

        @throws std::logic_error Always, because posting is not

        @throws std::logic_error Always, because posting is not

            supported in a blocking context.

            supported in a blocking context.

        @param h The coroutine handle (unused).

        @param h The coroutine handle (unused).

    */

    */

    [[noreturn]] void

    [[noreturn]] void

    {

    {

        throw std::logic_error(

        throw std::logic_error(

    }

    }

};

};

inline inline_context::executor_type

inline inline_context::executor_type

inline_context::get_executor() noexcept

inline_context::get_executor() noexcept

{

{

    return inline_executor{};

    return inline_executor{};

}

}

static_assert(Executor<inline_executor>);

static_assert(Executor<inline_executor>);

static_assert(ExecutionContext<inline_context>);

static_assert(ExecutionContext<inline_context>);

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

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

//

//

// blocking_state

// blocking_state

//

//

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

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

/** Synchronization state for blocking execution.

/** Synchronization state for blocking execution.

    Holds the mutex, condition variable, and completion flag

    Holds the mutex, condition variable, and completion flag

    used to block the caller until the task completes.

    used to block the caller until the task completes.

    @par Thread Safety

    @par Thread Safety

    Thread-safe when accessed under the mutex.

    Thread-safe when accessed under the mutex.

    @see run_blocking

    @see run_blocking

    @see blocking_handler_wrapper

    @see blocking_handler_wrapper

*/

*/

struct blocking_state

struct blocking_state

{

{

    std::mutex mtx;

    std::mutex mtx;

    std::condition_variable cv;

    std::condition_variable cv;

    bool done = false;

    bool done = false;

    std::exception_ptr ep;

    std::exception_ptr ep;

};

};

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

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

//

//

// blocking_handler_wrapper

// blocking_handler_wrapper

//

//

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

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

/** Wrapper that signals completion after invoking the underlying handler_pair.

/** Wrapper that signals completion after invoking the underlying handler_pair.

    This wrapper forwards invocations to the contained handler_pair,

    This wrapper forwards invocations to the contained handler_pair,

    then signals the `blocking_state` condition variable so

    then signals the `blocking_state` condition variable so

    that `run_blocking` can unblock. Any exceptions thrown by the

    that `run_blocking` can unblock. Any exceptions thrown by the

    handler are captured and stored for later rethrow.

    handler are captured 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. Signals the condition

    Safe to invoke from any thread. Signals the condition

    variable after calling the handler.

    variable after calling the handler.

    @see run_blocking

    @see run_blocking

    @see blocking_state

    @see blocking_state

*/

*/

template<class H1, class H2>

template<class H1, class H2>

struct blocking_handler_wrapper

struct blocking_handler_wrapper

{

{

    blocking_state* state_;

    blocking_state* state_;

    detail::handler_pair<H1, H2> handlers_;

    detail::handler_pair<H1, H2> handlers_;

    /** Invoke the handler with non-void result and signal completion. */

    /** Invoke the handler with non-void result and signal completion. */

    template<class T>

    template<class T>

    {

    {

        try

        try

        {

        {

        }

        }

        catch(...)

        catch(...)

        {

        {

            std::lock_guard<std::mutex> lock(state_->mtx);

            std::lock_guard<std::mutex> lock(state_->mtx);

            state_->ep = std::current_exception();

            state_->ep = std::current_exception();

            state_->done = true;

            state_->done = true;

            state_->cv.notify_one();

            state_->cv.notify_one();

            return;

            return;

        }

        }

        {

        {

    }

    }

    /** Invoke the handler for void result and signal completion. */

    /** Invoke the handler for void result and signal completion. */

    {

    {

        try

        try

        {

        {

        }

        }

        catch(...)

        catch(...)

        {

        {

            std::lock_guard<std::mutex> lock(state_->mtx);

            std::lock_guard<std::mutex> lock(state_->mtx);

            state_->ep = std::current_exception();

            state_->ep = std::current_exception();

            state_->done = true;

            state_->done = true;

            state_->cv.notify_one();

            state_->cv.notify_one();

            return;

            return;

        }

        }

        {

        {

    }

    }

    /** Invoke the handler with exception and signal completion. */

    /** Invoke the handler with exception and signal completion. */

    {

    {

        try

        try

        {

        {

        }

        }

        {

        {

        {

        {

    }

    }

};

};

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

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

//

//

// run_blocking_wrapper

// run_blocking_wrapper

//

//

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

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

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

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

    This wrapper holds the blocking state and handlers. When invoked

    This wrapper holds the blocking state and handlers. When invoked

    with a task, it launches the task via `run_async` and blocks

    with a task, it launches the task via `run_async` and blocks

    until the task completes.

    until the task completes.

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

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

    can only be used as a temporary.

    can only be used as a temporary.

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

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

    @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

    // Block until task completes

    // Block until task completes

    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

    @see run_blocking

    @see run_async

    @see run_async

*/

*/

template<Executor Ex, class H1, class H2>

template<Executor Ex, class H1, class H2>

class [[nodiscard]] run_blocking_wrapper

class [[nodiscard]] run_blocking_wrapper

{

{

    Ex ex_;

    Ex ex_;

    std::stop_token st_;

    std::stop_token st_;

    H1 h1_;

    H1 h1_;

    H2 h2_;

    H2 h2_;

public:

public:

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

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

        @param ex The executor to execute the task on.

        @param ex The executor to execute the task on.

        @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.

    */

    */

        Ex ex,

        Ex ex,

        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.

        This operator accepts a task, launches it via `run_async`

        This operator accepts a task, launches it via `run_async`

        with wrapped handlers, and blocks until the task completes.

        with wrapped handlers, and blocks until the task completes.

        @tparam Task The IoLaunchableTask type.

        @tparam Task The IoLaunchableTask type.

        @param t The task to execute.

        @param t The task to execute.

    */

    */

    template<IoLaunchableTask Task>

    template<IoLaunchableTask Task>

    void

    void

    {

    {

            if constexpr(std::is_same_v<H2, detail::default_handler>)

            if constexpr(std::is_same_v<H2, detail::default_handler>)

            else

            else

        };

        };

        run_async(

        run_async(

            ex_,

            ex_,

};

};

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

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

//

//

// run_blocking Overloads

// run_blocking Overloads

//

//

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

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

// With inline_executor (default)

// With inline_executor (default)

/** Block until task completes and discard result.

/** Block until task completes and discard result.

    Executes a lazy task using the inline executor and blocks the

    Executes a lazy task using the inline executor and blocks the

    calling thread until the task completes or throws.

    calling thread until the task completes or throws.

    @par Thread Safety

    @par Thread Safety

    The calling thread is blocked. The task executes inline

    The calling thread is blocked. The task executes inline

    on the calling thread.

    on the calling thread.

    @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<

        inline_executor,

        inline_executor,

        detail::default_handler,

        detail::default_handler,

        detail::default_handler>(

        detail::default_handler>(

            inline_executor{},

            inline_executor{},

            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 using the inline executor and blocks until

    Executes a lazy task using the inline executor and blocks until

    completion. The handler `h1` is called with the result on success.

    completion. The handler `h1` is called with the result on success.

    If `h1` is also invocable with `std::exception_ptr`, it handles

    If `h1` is also invocable with `std::exception_ptr`, it handles

    exceptions too. Otherwise, exceptions are rethrown.

    exceptions too. Otherwise, exceptions are rethrown.

    @par Thread Safety

    @par Thread Safety

    The calling thread is blocked. The task and handler execute

    The calling thread is blocked. The task and handler execute

    inline on the calling thread.

    inline on the calling thread.

    @par Exception Safety

    @par Exception Safety

    Basic guarantee. Exceptions from the task are passed to `h1`

    Basic guarantee. Exceptions from the task are passed to `h1`

    if it accepts `std::exception_ptr`, otherwise rethrown.

    if it accepts `std::exception_ptr`, otherwise rethrown.

    @par Example

    @par Example

    @code

    @code

    int result = 0;

    int result = 0;

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

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

    @endcode

    @endcode

    @param h1 Handler invoked with the result on success, and

    @param h1 Handler invoked with the result on success, and

        optionally with `std::exception_ptr` on failure.

        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<

        inline_executor,

        inline_executor,

        H1,

        H1,

        detail::default_handler>(

        detail::default_handler>(

            inline_executor{},

            inline_executor{},

}

}

/** Block until task completes with separate handlers.

/** Block until task completes with separate handlers.

    Executes a lazy task using the inline executor and blocks until

    Executes a lazy task using the inline executor and blocks until

    completion. The handler `h1` is called on success, `h2` on failure.

    completion. The handler `h1` is called on success, `h2` on failure.

    @par Thread Safety

    @par Thread Safety

    The calling thread is blocked. The task and handlers execute

    The calling thread is blocked. The task and handlers execute

    inline on the calling thread.

    inline on the calling thread.

    @par Exception Safety

    @par Exception Safety

    Basic guarantee. Exceptions from the task are passed to `h2`.

    Basic guarantee. Exceptions from the task are passed 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_value());

    )(compute_value());

    @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<

        inline_executor,

        inline_executor,

        H1,

        H1,

        H2>(

        H2>(

            inline_executor{},

            inline_executor{},

}

}

// With explicit executor

// With explicit executor

/** Block until task completes on the given executor.

/** Block until task completes on the given executor.

    Executes a lazy task on the specified executor and blocks the

    Executes a lazy task on the specified executor and blocks the

    calling thread until the task completes.

    calling thread until the task completes.

    @par Thread Safety

    @par Thread Safety

    The calling thread is blocked. The task may execute on

    The calling thread is blocked. The task may execute on

    a different thread depending on the executor.

    a different thread depending on the executor.

    @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_executor)(my_void_task());

    run_blocking(my_executor)(my_void_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 for blocking execution.

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

    @see run_async

    @see run_async

*/

*/

template<Executor Ex>

template<Executor Ex>

[[nodiscard]] auto

[[nodiscard]] auto

run_blocking(Ex ex)

run_blocking(Ex ex)

{

{

    return run_blocking_wrapper<

    return run_blocking_wrapper<

        Ex,

        Ex,

        detail::default_handler,

        detail::default_handler,

        detail::default_handler>(

        detail::default_handler>(

            std::move(ex),

            std::move(ex),

            std::stop_token{},

            std::stop_token{},

            detail::default_handler{},

            detail::default_handler{},

            detail::default_handler{});

            detail::default_handler{});

}

}

/** Block until task completes on executor with handler.

/** Block until task completes on executor with handler.

    Executes a lazy task on the specified executor and blocks until

    Executes a lazy task on the specified executor and blocks until

    completion. The handler `h1` is called with the result.

    completion. The handler `h1` is called with the result.

    @par Thread Safety

    @par Thread Safety

    The calling thread is blocked. The task and handler may

    The calling thread is blocked. The task and handler may

    execute on a different thread depending on the executor.

    execute on a different thread depending on the executor.

    @par Exception Safety

    @par Exception Safety

    Basic guarantee. Exceptions from the task are passed to `h1`

    Basic guarantee. Exceptions from the task are passed to `h1`

    if it accepts `std::exception_ptr`, otherwise rethrown.

    if it accepts `std::exception_ptr`, otherwise rethrown.

    @param ex The executor to execute the task on.

    @param ex The executor to execute the task on.