Diff coverage report for

//

//

// Copyright (c) 2026 Michael Vandeberg

// Copyright (c) 2026 Michael Vandeberg

// Copyright (c) 2026 Steve Gerbino

// Copyright (c) 2026 Steve Gerbino

//

//

// 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_WHEN_ANY_HPP

#ifndef BOOST_CAPY_WHEN_ANY_HPP

#define BOOST_CAPY_WHEN_ANY_HPP

#define BOOST_CAPY_WHEN_ANY_HPP

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

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

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

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

#include <boost/capy/continuation.hpp>

#include <boost/capy/continuation.hpp>

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

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

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

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

#include <coroutine>

#include <coroutine>

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

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

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

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

#include <boost/capy/task.hpp>

#include <boost/capy/task.hpp>

#include <array>

#include <array>

#include <atomic>

#include <atomic>

#include <exception>

#include <exception>

#include <memory>

#include <memory>

#include <mutex>

#include <mutex>

#include <optional>

#include <optional>

#include <ranges>

#include <ranges>

#include <stdexcept>

#include <stdexcept>

#include <stop_token>

#include <stop_token>

#include <tuple>

#include <tuple>

#include <type_traits>

#include <type_traits>

#include <utility>

#include <utility>

#include <variant>

#include <variant>

#include <vector>

#include <vector>

/*

/*

   when_any - Race multiple io_result tasks, select first success

   when_any - Race multiple io_result tasks, select first success

   =============================================================

   =============================================================

   OVERVIEW:

   OVERVIEW:

   ---------

   ---------

   when_any launches N io_result-returning tasks concurrently. A task

   when_any launches N io_result-returning tasks concurrently. A task

   wins by returning !ec; errors and exceptions do not win. Once a

   wins by returning !ec; errors and exceptions do not win. Once a

   winner is found, stop is requested for siblings and the winner's

   winner is found, stop is requested for siblings and the winner's

   payload is returned. If no winner exists (all fail), the first

   payload is returned. If no winner exists (all fail), the first

   error_code is returned or the last exception is rethrown.

   error_code is returned or the last exception is rethrown.

   ARCHITECTURE:

   ARCHITECTURE:

   -------------

   -------------

   The design mirrors when_all but with inverted completion semantics:

   The design mirrors when_all but with inverted completion semantics:

     when_all:  complete when remaining_count reaches 0 (all done)

     when_all:  complete when remaining_count reaches 0 (all done)

     when_any:  complete when has_winner becomes true (first done)

     when_any:  complete when has_winner becomes true (first done)

                BUT still wait for remaining_count to reach 0 for cleanup

                BUT still wait for remaining_count to reach 0 for cleanup

   Key components:

   Key components:

     - when_any_core:    Shared state tracking winner and completion

     - when_any_core:    Shared state tracking winner and completion

     - when_any_io_runner: Wrapper coroutine for each child task

     - when_any_io_runner: Wrapper coroutine for each child task

     - when_any_io_launcher/when_any_io_homogeneous_launcher:

     - when_any_io_launcher/when_any_io_homogeneous_launcher:

                          Awaitables that start all runners concurrently

                          Awaitables that start all runners concurrently

   CRITICAL INVARIANTS:

   CRITICAL INVARIANTS:

   --------------------

   --------------------

   1. Only a task returning !ec can become the winner (via atomic CAS)

   1. Only a task returning !ec can become the winner (via atomic CAS)

   2. All tasks must complete before parent resumes (cleanup safety)

   2. All tasks must complete before parent resumes (cleanup safety)

   3. Stop is requested immediately when winner is determined

   3. Stop is requested immediately when winner is determined

   4. Exceptions and errors do not claim winner status

   4. Exceptions and errors do not claim winner status

   POSITIONAL VARIANT:

   POSITIONAL VARIANT:

   -------------------

   -------------------

   The variadic overload returns std::variant<error_code, R1, R2, ..., Rn>.

   The variadic overload returns std::variant<error_code, R1, R2, ..., Rn>.

   Index 0 is error_code (failure/no-winner). Index 1..N identifies the

   Index 0 is error_code (failure/no-winner). Index 1..N identifies the

   winning child and carries its payload.

   winning child and carries its payload.

   RANGE OVERLOAD:

   RANGE OVERLOAD:

   ---------------

   ---------------

   The range overload returns variant<error_code, pair<size_t, T>> for

   The range overload returns variant<error_code, pair<size_t, T>> for

   non-void children or variant<error_code, size_t> for void children.

   non-void children or variant<error_code, size_t> for void children.

   MEMORY MODEL:

   MEMORY MODEL:

   -------------

   -------------

   Synchronization chain from winner's write to parent's read:

   Synchronization chain from winner's write to parent's read:

   1. Winner thread writes result_ (non-atomic)

   1. Winner thread writes result_ (non-atomic)

   2. Winner thread calls signal_completion() -> fetch_sub(acq_rel) on remaining_count_

   2. Winner thread calls signal_completion() -> fetch_sub(acq_rel) on remaining_count_

   3. Last task thread (may be winner or non-winner) calls signal_completion()

   3. Last task thread (may be winner or non-winner) calls signal_completion()

      -> fetch_sub(acq_rel) on remaining_count_, observing count becomes 0

      -> fetch_sub(acq_rel) on remaining_count_, observing count becomes 0

   4. Last task returns caller_ex_.dispatch(continuation_) via symmetric transfer

   4. Last task returns caller_ex_.dispatch(continuation_) via symmetric transfer

   5. Parent coroutine resumes and reads result_

   5. Parent coroutine resumes and reads result_

   Synchronization analysis:

   Synchronization analysis:

   - All fetch_sub operations on remaining_count_ form a release sequence

   - All fetch_sub operations on remaining_count_ form a release sequence

   - Winner's fetch_sub releases; subsequent fetch_sub operations participate

   - Winner's fetch_sub releases; subsequent fetch_sub operations participate

     in the modification order of remaining_count_

     in the modification order of remaining_count_

   - Last task's fetch_sub(acq_rel) synchronizes-with prior releases in the

   - Last task's fetch_sub(acq_rel) synchronizes-with prior releases in the

     modification order, establishing happens-before from winner's writes

     modification order, establishing happens-before from winner's writes

   - Executor dispatch() is expected to provide queue-based synchronization

   - Executor dispatch() is expected to provide queue-based synchronization

     (release-on-post, acquire-on-execute) completing the chain to parent

     (release-on-post, acquire-on-execute) completing the chain to parent

   - Even inline executors work (same thread = sequenced-before)

   - Even inline executors work (same thread = sequenced-before)

   EXCEPTION SEMANTICS:

   EXCEPTION SEMANTICS:

   --------------------

   --------------------

   Exceptions do NOT claim winner status. If a child throws, the exception

   Exceptions do NOT claim winner status. If a child throws, the exception

   is recorded but the combinator keeps waiting for a success. Only when

   is recorded but the combinator keeps waiting for a success. Only when

   all children complete without a winner does the combinator check: if

   all children complete without a winner does the combinator check: if

   any exception was recorded, it is rethrown (exception beats error_code).

   any exception was recorded, it is rethrown (exception beats error_code).

*/

*/

namespace boost {

namespace boost {

namespace capy {

namespace capy {

namespace detail {

namespace detail {

/** Core shared state for when_any operations.

/** Core shared state for when_any operations.

    Contains all members and methods common to both heterogeneous (variadic)

    Contains all members and methods common to both heterogeneous (variadic)

    and homogeneous (range) when_any implementations. State classes embed

    and homogeneous (range) when_any implementations. State classes embed

    this via composition to avoid CRTP destructor ordering issues.

    this via composition to avoid CRTP destructor ordering issues.

    @par Thread Safety

    @par Thread Safety

    Atomic operations protect winner selection and completion count.

    Atomic operations protect winner selection and completion count.

*/

*/

struct when_any_core

struct when_any_core

{

{

    std::atomic<std::size_t> remaining_count_;

    std::atomic<std::size_t> remaining_count_;

    std::size_t winner_index_{0};

    std::size_t winner_index_{0};

    std::exception_ptr winner_exception_;

    std::exception_ptr winner_exception_;

    std::stop_source stop_source_;

    std::stop_source stop_source_;

    // Bridges parent's stop token to our stop_source

    // Bridges parent's stop token to our stop_source

    struct stop_callback_fn

    struct stop_callback_fn

    {

    {

        std::stop_source* source_;

        std::stop_source* source_;

    };

    };

    using stop_callback_t = std::stop_callback<stop_callback_fn>;

    using stop_callback_t = std::stop_callback<stop_callback_fn>;

    std::optional<stop_callback_t> parent_stop_callback_;

    std::optional<stop_callback_t> parent_stop_callback_;

    continuation continuation_;

    continuation continuation_;

    io_env const* caller_env_ = nullptr;

    io_env const* caller_env_ = nullptr;

    // Placed last to avoid padding (1-byte atomic followed by 8-byte aligned members)

    // Placed last to avoid padding (1-byte atomic followed by 8-byte aligned members)

    std::atomic<bool> has_winner_{false};

    std::atomic<bool> has_winner_{false};

    {

    {

    /** Atomically claim winner status; exactly one task succeeds. */

    /** Atomically claim winner status; exactly one task succeeds. */

    {

    {

            expected, true, std::memory_order_acq_rel))

            expected, true, std::memory_order_acq_rel))

        {

        {

        }

        }

    }

    }

    /** @pre try_win() returned true. */

    /** @pre try_win() returned true. */

    {

    {

    // Runners signal completion directly via final_suspend; no member function needed.

    // Runners signal completion directly via final_suspend; no member function needed.

};

};

} // namespace detail

} // namespace detail

namespace detail {

namespace detail {

// State for io_result-aware when_any: only !ec wins.

// State for io_result-aware when_any: only !ec wins.

template<typename... Ts>

template<typename... Ts>

struct when_any_io_state

struct when_any_io_state

{

{

    static constexpr std::size_t task_count = sizeof...(Ts);

    static constexpr std::size_t task_count = sizeof...(Ts);

    using variant_type = std::variant<std::error_code, Ts...>;

    using variant_type = std::variant<std::error_code, Ts...>;

    when_any_core core_;

    when_any_core core_;

    std::optional<variant_type> result_;

    std::optional<variant_type> result_;

    std::array<continuation, task_count> runner_handles_{};

    std::array<continuation, task_count> runner_handles_{};

    // Last failure (error or exception) for the all-fail case.

    // Last failure (error or exception) for the all-fail case.

    // Last writer wins — no priority between errors and exceptions.

    // Last writer wins — no priority between errors and exceptions.

    std::mutex failure_mu_;

    std::mutex failure_mu_;

    std::error_code last_error_;

    std::error_code last_error_;

    std::exception_ptr last_exception_;

    std::exception_ptr last_exception_;

    {

    {

    {

    {

    {

    {

};

};

// Wrapper coroutine for io_result-aware when_any children.

// Wrapper coroutine for io_result-aware when_any children.

// unhandled_exception records the exception but does NOT claim winner status.

// unhandled_exception records the exception but does NOT claim winner status.

template<typename StateType>

template<typename StateType>

struct BOOST_CAPY_CORO_DESTROY_WHEN_COMPLETE when_any_io_runner

struct BOOST_CAPY_CORO_DESTROY_WHEN_COMPLETE when_any_io_runner

{

{

    struct promise_type

    struct promise_type

        : frame_alloc_mixin

        : frame_alloc_mixin

    {

    {

        StateType* state_ = nullptr;

        StateType* state_ = nullptr;

        std::size_t index_ = 0;

        std::size_t index_ = 0;

        io_env env_;

        io_env env_;

        {

        {

            return when_any_io_runner(

            return when_any_io_runner(

        }

        }

        {

        {

            struct awaiter

            struct awaiter

            {

            {

                promise_type* p_;

                promise_type* p_;

                {

                {

                }

                }

            };

            };

        }

        }

        // Exceptions do NOT win in io_result when_any

        // Exceptions do NOT win in io_result when_any

        {

        {

        template<class Awaitable>

        template<class Awaitable>

        struct transform_awaiter

        struct transform_awaiter

        {

        {

            std::decay_t<Awaitable> a_;

            std::decay_t<Awaitable> a_;

            promise_type* p_;

            promise_type* p_;

            template<class Promise>

            template<class Promise>

            {

            {

                using R = decltype(a_.await_suspend(h, &p_->env_));

                using R = decltype(a_.await_suspend(h, &p_->env_));

                if constexpr (std::is_same_v<R, std::coroutine_handle<>>)

                if constexpr (std::is_same_v<R, std::coroutine_handle<>>)

                else

                else

                    return a_.await_suspend(h, &p_->env_);

                    return a_.await_suspend(h, &p_->env_);

            }

            }

        };

        };

        template<class Awaitable>

        template<class Awaitable>

        {

        {

            using A = std::decay_t<Awaitable>;

            using A = std::decay_t<Awaitable>;

            if constexpr (IoAwaitable<A>)

            if constexpr (IoAwaitable<A>)

            {

            {

                return transform_awaiter<Awaitable>{

                return transform_awaiter<Awaitable>{

            }

            }

            else

            else

            {

            {

                static_assert(sizeof(A) == 0, "requires IoAwaitable");

                static_assert(sizeof(A) == 0, "requires IoAwaitable");

            }

            }

    };

    };

    std::coroutine_handle<promise_type> h_;

    std::coroutine_handle<promise_type> h_;

    {

    {

    when_any_io_runner(when_any_io_runner&& other) noexcept

    when_any_io_runner(when_any_io_runner&& other) noexcept

        : h_(std::exchange(other.h_, nullptr))

        : h_(std::exchange(other.h_, nullptr))

    {

    {

    }

    }

    when_any_io_runner(when_any_io_runner const&) = delete;

    when_any_io_runner(when_any_io_runner const&) = delete;

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

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

    when_any_io_runner& operator=(when_any_io_runner&&) = delete;

    when_any_io_runner& operator=(when_any_io_runner&&) = delete;

    {

    {

    }

    }

};

};

// Runner coroutine: only tries to win when the child returns !ec.

// Runner coroutine: only tries to win when the child returns !ec.

template<std::size_t I, IoAwaitable Awaitable, typename StateType>

template<std::size_t I, IoAwaitable Awaitable, typename StateType>

when_any_io_runner<StateType>

when_any_io_runner<StateType>

{

{

    auto result = co_await std::move(inner);

    auto result = co_await std::move(inner);

    if(!result.ec)

    if(!result.ec)

    {

    {

        // Success: try to claim winner

        // Success: try to claim winner

        if(state->core_.try_win(I))

        if(state->core_.try_win(I))

        {

        {

            try

            try

            {

            {

                state->result_.emplace(

                state->result_.emplace(

                    std::in_place_index<I + 1>,

                    std::in_place_index<I + 1>,

                    detail::extract_io_payload(std::move(result)));

                    detail::extract_io_payload(std::move(result)));

            }

            }

            catch(...)

            catch(...)

            {

            {

                state->core_.set_winner_exception(std::current_exception());

                state->core_.set_winner_exception(std::current_exception());

            }

            }

        }

        }

    }

    }

    else

    else

    {

    {

        // Error: record but don't win

        // Error: record but don't win

        state->record_error(result.ec);

        state->record_error(result.ec);

    }

    }

// Launcher for io_result-aware when_any.

// Launcher for io_result-aware when_any.

template<IoAwaitable... Awaitables>

template<IoAwaitable... Awaitables>

class when_any_io_launcher

class when_any_io_launcher

{

{

    using state_type = when_any_io_state<

    using state_type = when_any_io_state<

        io_result_payload_t<awaitable_result_t<Awaitables>>...>;

        io_result_payload_t<awaitable_result_t<Awaitables>>...>;

    std::tuple<Awaitables...>* tasks_;

    std::tuple<Awaitables...>* tasks_;

    state_type* state_;

    state_type* state_;

public:

public:

        std::tuple<Awaitables...>* tasks,

        std::tuple<Awaitables...>* tasks,

        state_type* state)

        state_type* state)

    {

    {

    {

    {

    }

    }

        std::coroutine_handle<> continuation, io_env const* caller_env)

        std::coroutine_handle<> continuation, io_env const* caller_env)

    {

    {

        {

        {

        }

        }

private:

private:

    template<std::size_t I>

    template<std::size_t I>

    {

    {

};

};

/** Shared state for homogeneous io_result-aware when_any (range overload).

/** Shared state for homogeneous io_result-aware when_any (range overload).

    @tparam T The payload type extracted from io_result.

    @tparam T The payload type extracted from io_result.

*/

*/

template<typename T>

template<typename T>

struct when_any_io_homogeneous_state

struct when_any_io_homogeneous_state

{

{

    when_any_core core_;

    when_any_core core_;

    std::optional<T> result_;

    std::optional<T> result_;

    std::unique_ptr<continuation[]> runner_handles_;

    std::unique_ptr<continuation[]> runner_handles_;

    std::mutex failure_mu_;

    std::mutex failure_mu_;

    std::error_code last_error_;

    std::error_code last_error_;

    std::exception_ptr last_exception_;

    std::exception_ptr last_exception_;

    {

    {

    {

    {

    {

    {

};

};

/** Specialization for void io_result children (no payload storage). */

/** Specialization for void io_result children (no payload storage). */

template<>

template<>

struct when_any_io_homogeneous_state<std::tuple<>>

struct when_any_io_homogeneous_state<std::tuple<>>

{

{

    when_any_core core_;

    when_any_core core_;

    std::unique_ptr<continuation[]> runner_handles_;

    std::unique_ptr<continuation[]> runner_handles_;

    std::mutex failure_mu_;

    std::mutex failure_mu_;

    std::error_code last_error_;

    std::error_code last_error_;

    std::exception_ptr last_exception_;

    std::exception_ptr last_exception_;

    {

    {

    {

    {

    {

    {

};

};

/** Create an io_result-aware runner for homogeneous when_any (range path).

/** Create an io_result-aware runner for homogeneous when_any (range path).

    Only tries to win when the child returns !ec.

    Only tries to win when the child returns !ec.

*/

*/

template<IoAwaitable Awaitable, typename StateType>

template<IoAwaitable Awaitable, typename StateType>

when_any_io_runner<StateType>

when_any_io_runner<StateType>

    Awaitable inner, StateType* state, std::size_t index)

    Awaitable inner, StateType* state, std::size_t index)

{

{

    auto result = co_await std::move(inner);

    auto result = co_await std::move(inner);

    if(!result.ec)

    if(!result.ec)

    {

    {

        if(state->core_.try_win(index))

        if(state->core_.try_win(index))

        {

        {

            using PayloadT = io_result_payload_t<

            using PayloadT = io_result_payload_t<

                awaitable_result_t<Awaitable>>;

                awaitable_result_t<Awaitable>>;

            if constexpr (!std::is_same_v<PayloadT, std::tuple<>>)

            if constexpr (!std::is_same_v<PayloadT, std::tuple<>>)

            {

            {

                try

                try

                {

                {

                    state->result_.emplace(

                    state->result_.emplace(

                        extract_io_payload(std::move(result)));

                        extract_io_payload(std::move(result)));

                }

                }

                catch(...)

                catch(...)

                {

                {

                    state->core_.set_winner_exception(

                    state->core_.set_winner_exception(

                        std::current_exception());

                        std::current_exception());

                }

                }

            }

            }

        }

        }

    }

    }

    else

    else

    {

    {

        state->record_error(result.ec);

        state->record_error(result.ec);

    }

    }