include/boost/capy/when_any.hpp

100.0% Lines (165/1/166) 92.6% List of functions (251/2/273)

[ ] prev/next file n p prev/next uncovered line

when_any.hpp

f(x) Functions (273)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2026 Michael Vandeberg
3		// Copyright (c) 2026 Steve Gerbino
4		//
5		// Distributed under the Boost Software License, Version 1.0. (See accompanying
6		// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7		//
8		// Official repository: https://github.com/cppalliance/capy
9		//
10
11		#ifndef BOOST_CAPY_WHEN_ANY_HPP
12		#define BOOST_CAPY_WHEN_ANY_HPP
13
14		#include <boost/capy/detail/config.hpp>
15		#include <boost/capy/detail/io_result_combinators.hpp>
16		#include <boost/capy/continuation.hpp>
17		#include <boost/capy/concept/executor.hpp>
18		#include <boost/capy/concept/io_awaitable.hpp>
19		#include <coroutine>
20		#include <boost/capy/ex/executor_ref.hpp>
21		#include <boost/capy/ex/frame_alloc_mixin.hpp>
22		#include <boost/capy/ex/frame_allocator.hpp>
23		#include <boost/capy/ex/io_env.hpp>
24		#include <boost/capy/task.hpp>
25
26		#include <array>
27		#include <atomic>
28		#include <exception>
29		#include <memory>
30		#include <mutex>
31		#include <optional>
32		#include <ranges>
33		#include <stdexcept>
34		#include <stop_token>
35		#include <tuple>
36		#include <type_traits>
37		#include <utility>
38		#include <variant>
39		#include <vector>
40
41		/*
42		when_any - Race multiple io_result tasks, select first success
43		=============================================================
44
45		OVERVIEW:
46		---------
47		when_any launches N io_result-returning tasks concurrently. A task
48		wins by returning !ec; errors and exceptions do not win. Once a
49		winner is found, stop is requested for siblings and the winner's
50		payload is returned. If no winner exists (all fail), one of the
51		failures is surfaced (an error_code at variant index 0, or a child's
52		exception rethrown); which one is unspecified.
53
54		ARCHITECTURE:
55		-------------
56		The design mirrors when_all but with inverted completion semantics:
57
58		when_all: complete when remaining_count reaches 0 (all done)
59		when_any: complete when has_winner becomes true (first done)
60		BUT still wait for remaining_count to reach 0 for cleanup
61
62		Key components:
63		- when_any_core: Shared state tracking winner and completion
64		- when_any_io_runner: Wrapper coroutine for each child task
65		- when_any_io_launcher/when_any_io_homogeneous_launcher:
66		Awaitables that start all runners concurrently
67
68		CRITICAL INVARIANTS:
69		--------------------
70		1. Only a task returning !ec can become the winner (via atomic CAS)
71		2. All tasks must complete before parent resumes (cleanup safety)
72		3. Stop is requested immediately when winner is determined
73		4. Exceptions and errors do not claim winner status
74
75		POSITIONAL VARIANT:
76		-------------------
77		The variadic overload returns std::variant<error_code, R1, R2, ..., Rn>.
78		Index 0 is error_code (failure/no-winner). Index 1..N identifies the
79		winning child and carries its payload.
80
81		RANGE OVERLOAD:
82		---------------
83		The range overload returns variant<error_code, pair<size_t, T>> for
84		non-void children or variant<error_code, size_t> for void children.
85
86		MEMORY MODEL:
87		-------------
88		Synchronization chain from winner's write to parent's read:
89
90		1. Winner thread writes result_ (non-atomic)
91		2. Winner thread calls signal_completion() -> fetch_sub(acq_rel) on remaining_count_
92		3. Last task thread (may be winner or non-winner) calls signal_completion()
93		-> fetch_sub(acq_rel) on remaining_count_, observing count becomes 0
94		4. Last task returns caller_ex_.dispatch(continuation_) via symmetric transfer
95		5. Parent coroutine resumes and reads result_
96
97		Synchronization analysis:
98		- All fetch_sub operations on remaining_count_ form a release sequence
99		- Winner's fetch_sub releases; subsequent fetch_sub operations participate
100		in the modification order of remaining_count_
101		- Last task's fetch_sub(acq_rel) synchronizes-with prior releases in the
102		modification order, establishing happens-before from winner's writes
103		- Executor dispatch() is expected to provide queue-based synchronization
104		(release-on-post, acquire-on-execute) completing the chain to parent
105		- Even inline executors work (same thread = sequenced-before)
106
107		EXCEPTION SEMANTICS:
108		--------------------
109		Exceptions do NOT claim winner status. If a child throws, the exception
110		is recorded but the combinator keeps waiting for a success. Only when
111		all children complete without a winner is a failure surfaced. There is
112		no priority between errors and exceptions, and no guarantee about which
113		child's failure is reported: the result either returns an error_code at
114		variant index 0 or rethrows a child's exception.
115		*/
116
117		namespace boost {
118		namespace capy {
119
120		namespace detail {
121
122		/** Core shared state for when_any operations.
123
124		Contains all members and methods common to both heterogeneous (variadic)
125		and homogeneous (range) when_any implementations. State classes embed
126		this via composition to avoid CRTP destructor ordering issues.
127
128		@par Thread Safety
129		Atomic operations protect winner selection and completion count.
130		*/
131		struct when_any_core
132		{
133		std::atomic<std::size_t> remaining_count_;
134		std::size_t winner_index_{0};
135		std::exception_ptr winner_exception_;
136		std::stop_source stop_source_;
137
138		// Bridges parent's stop token to our stop_source
139		struct stop_callback_fn
140		{
141		std::stop_source* source_;
142	3x	void operator()() const noexcept { source_->request_stop(); }
143		};
144		using stop_callback_t = std::stop_callback<stop_callback_fn>;
145		std::optional<stop_callback_t> parent_stop_callback_;
146
147		continuation continuation_;
148		io_env const* caller_env_ = nullptr;
149
150		// Placed last to avoid padding (1-byte atomic followed by 8-byte aligned members)
151		std::atomic<bool> has_winner_{false};
152
153	39x	explicit when_any_core(std::size_t count) noexcept
154	39x	: remaining_count_(count)
155		{
156	39x	}
157
158		/** Atomically claim winner status; exactly one task succeeds. */
159	60x	bool try_win(std::size_t index) noexcept
160		{
161	60x	bool expected = false;
162	60x	if(has_winner_.compare_exchange_strong(
163		expected, true, std::memory_order_acq_rel))
164		{
165	28x	winner_index_ = index;
166	28x	stop_source_.request_stop();
167	28x	return true;
168		}
169	32x	return false;
170		}
171
172		/** @pre try_win() returned true. */
173	1x	void set_winner_exception(std::exception_ptr ep) noexcept
174		{
175	1x	winner_exception_ = ep;
176	1x	}
177
178		// Runners signal completion directly via final_suspend; no member function needed.
179		};
180
181		} // namespace detail
182
183		namespace detail {
184
185		// State for io_result-aware when_any: only !ec wins.
186		template<typename... Ts>
187		struct when_any_io_state
188		{
189		static constexpr std::size_t task_count = sizeof...(Ts);
190		using variant_type = std::variant<std::error_code, Ts...>;
191
192		when_any_core core_;
193		std::optional<variant_type> result_;
194		std::array<continuation, task_count> runner_handles_{};
195
196		// A failure (error or exception) for the all-fail case. record_error
197		// and record_exception overwrite each other, so which one survives is
198		// unspecified (no priority between errors and exceptions).
199		std::mutex failure_mu_;
200		std::error_code last_error_;
201		std::exception_ptr last_exception_;
202
203	23x	when_any_io_state()
204	23x	: core_(task_count)
205		{
206	23x	}
207
208	15x	void record_error(std::error_code ec)
209		{
210	15x	std::lock_guard lk(failure_mu_);
211	15x	last_error_ = ec;
212	15x	last_exception_ = nullptr;
213	15x	}
214
215	7x	void record_exception(std::exception_ptr ep)
216		{
217	7x	std::lock_guard lk(failure_mu_);
218	7x	last_exception_ = ep;
219	7x	last_error_ = {};
220	7x	}
221		};
222
223		// Wrapper coroutine for io_result-aware when_any children.
224		// unhandled_exception records the exception but does NOT claim winner status.
225		template<typename StateType>
226		struct BOOST_CAPY_CORO_DESTROY_WHEN_COMPLETE when_any_io_runner
227		{
228		struct promise_type
229		: frame_alloc_mixin
230		{
231		StateType* state_ = nullptr;
232		std::size_t index_ = 0;
233		io_env env_;
234
235	95x	when_any_io_runner get_return_object() noexcept
236		{
237		return when_any_io_runner(
238	95x	std::coroutine_handle<promise_type>::from_promise(*this));
239		}
240
241	95x	std::suspend_always initial_suspend() noexcept { return {}; }
242
243	95x	auto final_suspend() noexcept
244		{
245		struct awaiter
246		{
247		promise_type* p_;
248	6x	bool await_ready() const noexcept { return false; }
249	6x	auto await_suspend(std::coroutine_handle<> h) noexcept
250		{
251	6x	auto& core = p_->state_->core_;
252	6x	auto* counter = &core.remaining_count_;
253	6x	auto* caller_env = core.caller_env_;
254	6x	auto& cont = core.continuation_;
255
256	6x	h.destroy();
257
258	6x	auto remaining = counter->fetch_sub(1, std::memory_order_acq_rel);
259	6x	if(remaining == 1)
260	3x	return detail::symmetric_transfer(caller_env->executor.dispatch(cont));
261	3x	return detail::symmetric_transfer(std::noop_coroutine());
262		}
263	−	void await_resume() const noexcept {} // LCOV_EXCL_LINE final_suspend awaiter, never resumed
264		};
265	95x	return awaiter{this};
266		}
267
268	82x	void return_void() noexcept {}
269
270		// Exceptions do NOT win in io_result when_any
271	13x	void unhandled_exception() noexcept
272		{
273	13x	state_->record_exception(std::current_exception());
274	13x	}
275
276		template<class Awaitable>
277		struct transform_awaiter
278		{
279		std::decay_t<Awaitable> a_;
280		promise_type* p_;
281
282	95x	bool await_ready() { return a_.await_ready(); }
283	95x	decltype(auto) await_resume() { return a_.await_resume(); }
284
285		template<class Promise>
286	94x	auto await_suspend(std::coroutine_handle<Promise> h)
287		{
288		using R = decltype(a_.await_suspend(h, &p_->env_));
289		if constexpr (std::is_same_v<R, std::coroutine_handle<>>)
290	94x	return detail::symmetric_transfer(a_.await_suspend(h, &p_->env_));
291		else
292		return a_.await_suspend(h, &p_->env_);
293		}
294		};
295
296		template<class Awaitable>
297	95x	auto await_transform(Awaitable&& a)
298		{
299		using A = std::decay_t<Awaitable>;
300		if constexpr (IoAwaitable<A>)
301		{
302		return transform_awaiter<Awaitable>{
303	188x	std::forward<Awaitable>(a), this};
304		}
305		else
306		{
307		static_assert(sizeof(A) == 0, "requires IoAwaitable");
308		}
309	93x	}
310		};
311
312		std::coroutine_handle<promise_type> h_;
313
314	95x	explicit when_any_io_runner(std::coroutine_handle<promise_type> h) noexcept
315	95x	: h_(h)
316		{
317	95x	}
318
319		when_any_io_runner(when_any_io_runner&& other) noexcept
320		: h_(std::exchange(other.h_, nullptr))
321		{
322		}
323
324		when_any_io_runner(when_any_io_runner const&) = delete;
325		when_any_io_runner& operator=(when_any_io_runner const&) = delete;
326		when_any_io_runner& operator=(when_any_io_runner&&) = delete;
327
328	95x	auto release() noexcept
329		{
330	95x	return std::exchange(h_, nullptr);
331		}
332		};
333
334		// Runner coroutine: only tries to win when the child returns !ec.
335		template<std::size_t I, IoAwaitable Awaitable, typename StateType>
336		when_any_io_runner<StateType>
337	41x	make_when_any_io_runner(Awaitable inner, StateType* state)
338		{
339		auto result = co_await std::move(inner);
340
341		if(!std::get<0>(result))
342		{
343		// Success: try to claim winner
344		if(state->core_.try_win(I))
345		{
346		try
347		{
348		state->result_.emplace(
349		std::in_place_index<I + 1>,
350		detail::extract_io_payload(std::move(result)));
351		}
352		catch(...)
353		{
354		state->core_.set_winner_exception(std::current_exception());
355		}
356		}
357		}
358		else
359		{
360		// Error: record but don't win
361		state->record_error(std::get<0>(result));
362		}
363	82x	}
364
365		// Launcher for io_result-aware when_any.
366		template<IoAwaitable... Awaitables>
367		class when_any_io_launcher
368		{
369		using state_type = when_any_io_state<
370		io_result_payload_t<awaitable_result_t<Awaitables>>...>;
371
372		std::tuple<Awaitables...>* tasks_;
373		state_type* state_;
374
375		public:
376	23x	when_any_io_launcher(
377		std::tuple<Awaitables...>* tasks,
378		state_type* state)
379	23x	: tasks_(tasks)
380	23x	, state_(state)
381		{
382	23x	}
383
384	23x	bool await_ready() const noexcept
385		{
386	23x	return sizeof...(Awaitables) == 0;
387		}
388
389	23x	std::coroutine_handle<> await_suspend(
390		std::coroutine_handle<> continuation, io_env const* caller_env)
391		{
392	23x	state_->core_.continuation_.h = continuation;
393	23x	state_->core_.caller_env_ = caller_env;
394
395	23x	if(caller_env->stop_token.stop_possible())
396		{
397	4x	state_->core_.parent_stop_callback_.emplace(
398	2x	caller_env->stop_token,
399	2x	when_any_core::stop_callback_fn{&state_->core_.stop_source_});
400
401	2x	if(caller_env->stop_token.stop_requested())
402	1x	state_->core_.stop_source_.request_stop();
403		}
404
405	23x	auto token = state_->core_.stop_source_.get_token();
406	23x	launch_all(std::index_sequence_for<Awaitables...>{},
407		caller_env->executor, token);
408
409	46x	return std::noop_coroutine();
410	23x	}
411
412	23x	void await_resume() const noexcept {}
413
414		private:
415		template<std::size_t... Is>
416	23x	void launch_all(std::index_sequence<Is...>,
417		executor_ref ex, std::stop_token token)
418		{
419	23x	(..., launch_one<Is>(ex, token));
420	23x	}
421
422		template<std::size_t I>
423	41x	void launch_one(executor_ref caller_ex, std::stop_token token)
424		{
425	41x	auto runner = make_when_any_io_runner<I>(
426	41x	std::move(std::get<I>(*tasks_)), state_);
427
428	41x	auto h = runner.release();
429	41x	h.promise().state_ = state_;
430	41x	h.promise().index_ = I;
431	41x	h.promise().env_ = io_env{caller_ex, token,
432	41x	state_->core_.caller_env_->frame_allocator};
433
434	41x	state_->runner_handles_[I].h = std::coroutine_handle<>{h};
435	41x	caller_ex.post(state_->runner_handles_[I]);
436	82x	}
437		};
438
439		/** Shared state for homogeneous io_result-aware when_any (range overload).
440
441		@tparam T The payload type extracted from io_result.
442		*/
443		template<typename T>
444		struct when_any_io_homogeneous_state
445		{
446		when_any_core core_;
447		std::optional<T> result_;
448		std::unique_ptr<continuation[]> runner_handles_;
449
450		std::mutex failure_mu_;
451		std::error_code last_error_;
452		std::exception_ptr last_exception_;
453
454	13x	explicit when_any_io_homogeneous_state(std::size_t count)
455	13x	: core_(count)
456	13x	, runner_handles_(std::make_unique<continuation[]>(count))
457		{
458	13x	}
459
460	6x	void record_error(std::error_code ec)
461		{
462	6x	std::lock_guard lk(failure_mu_);
463	6x	last_error_ = ec;
464	6x	last_exception_ = nullptr;
465	6x	}
466
467	4x	void record_exception(std::exception_ptr ep)
468		{
469	4x	std::lock_guard lk(failure_mu_);
470	4x	last_exception_ = ep;
471	4x	last_error_ = {};
472	4x	}
473		};
474
475		/** Specialization for void io_result children (no payload storage). */
476		template<>
477		struct when_any_io_homogeneous_state<std::tuple<>>
478		{
479		when_any_core core_;
480		std::unique_ptr<continuation[]> runner_handles_;
481
482		std::mutex failure_mu_;
483		std::error_code last_error_;
484		std::exception_ptr last_exception_;
485
486	3x	explicit when_any_io_homogeneous_state(std::size_t count)
487	3x	: core_(count)
488	3x	, runner_handles_(std::make_unique<continuation[]>(count))
489		{
490	3x	}
491
492	1x	void record_error(std::error_code ec)
493		{
494	1x	std::lock_guard lk(failure_mu_);
495	1x	last_error_ = ec;
496	1x	last_exception_ = nullptr;
497	1x	}
498
499	2x	void record_exception(std::exception_ptr ep)
500		{
501	2x	std::lock_guard lk(failure_mu_);
502	2x	last_exception_ = ep;
503	2x	last_error_ = {};
504	2x	}
505		};
506
507		/** Create an io_result-aware runner for homogeneous when_any (range path).
508
509		Only tries to win when the child returns !ec.
510		*/
511		template<IoAwaitable Awaitable, typename StateType>
512		when_any_io_runner<StateType>
513	54x	make_when_any_io_homogeneous_runner(
514		Awaitable inner, StateType* state, std::size_t index)
515		{
516		auto result = co_await std::move(inner);
517
518		if(!std::get<0>(result))
519		{
520		if(state->core_.try_win(index))
521		{
522		using PayloadT = io_result_payload_t<
523		awaitable_result_t<Awaitable>>;
524		if constexpr (!std::is_same_v<PayloadT, std::tuple<>>)
525		{
526		try
527		{
528		state->result_.emplace(
529		extract_io_payload(std::move(result)));
530		}
531		catch(...)
532		{
533		state->core_.set_winner_exception(
534		std::current_exception());
535		}
536		}
537		}
538		}
539		else
540		{
541		state->record_error(std::get<0>(result));
542		}
543	108x	}
544
545		/** Starts all io_result-aware homogeneous runners concurrently. */
546		template<IoAwaitableRange Range>
547		class when_any_io_homogeneous_launcher
548		{
549		using Awaitable = std::ranges::range_value_t<Range>;
550		using PayloadT = io_result_payload_t<awaitable_result_t<Awaitable>>;
551
552		Range* range_;
553		when_any_io_homogeneous_state<PayloadT>* state_;
554
555		public:
556	16x	when_any_io_homogeneous_launcher(
557		Range* range,
558		when_any_io_homogeneous_state<PayloadT>* state)
559	16x	: range_(range)
560	16x	, state_(state)
561		{
562	16x	}
563
564	16x	bool await_ready() const noexcept
565		{
566	16x	return std::ranges::empty(*range_);
567		}
568
569	16x	std::coroutine_handle<> await_suspend(
570		std::coroutine_handle<> continuation, io_env const* caller_env)
571		{
572	16x	state_->core_.continuation_.h = continuation;
573	16x	state_->core_.caller_env_ = caller_env;
574
575	16x	if(caller_env->stop_token.stop_possible())
576		{
577	4x	state_->core_.parent_stop_callback_.emplace(
578	2x	caller_env->stop_token,
579	2x	when_any_core::stop_callback_fn{&state_->core_.stop_source_});
580
581	2x	if(caller_env->stop_token.stop_requested())
582	1x	state_->core_.stop_source_.request_stop();
583		}
584
585	16x	auto token = state_->core_.stop_source_.get_token();
586
587		// Phase 1: Create all runners without dispatching.
588	16x	std::size_t index = 0;
589	70x	for(auto&& a : *range_)
590		{
591	54x	auto runner = make_when_any_io_homogeneous_runner(
592	54x	std::move(a), state_, index);
593
594	54x	auto h = runner.release();
595	54x	h.promise().state_ = state_;
596	54x	h.promise().index_ = index;
597	54x	h.promise().env_ = io_env{caller_env->executor, token,
598	54x	caller_env->frame_allocator};
599
600	54x	state_->runner_handles_[index].h = std::coroutine_handle<>{h};
601	54x	++index;
602		}
603
604		// Phase 2: Post all runners. Any may complete synchronously.
605	16x	auto* handles = state_->runner_handles_.get();
606	16x	std::size_t count = state_->core_.remaining_count_.load(std::memory_order_relaxed);
607	70x	for(std::size_t i = 0; i < count; ++i)
608	54x	caller_env->executor.post(handles[i]);
609
610	32x	return std::noop_coroutine();
611	70x	}
612
613	16x	void await_resume() const noexcept {}
614		};
615
616		} // namespace detail
617
618		/** Race a range of io_result-returning awaitables (non-void payloads).
619
620		Only a child returning !ec can win. Errors and exceptions do not
621		claim winner status. If all children fail, an unspecified one of
622		the failures is reported — either an error_code at variant index 0,
623		or a child's exception rethrown.
624
625		@par Await-effects
626
627		Takes ownership of the range, creates one wrapper coroutine per
628		element, then posts every wrapper to the caller's executor. All
629		children therefore run concurrently, each awaited with the caller's
630		executor and frame allocator and with a stop token owned by this
631		operation.
632
633		Awaiting an empty range throws `std::invalid_argument` before any
634		child is started.
635
636		The first child to await-return a zero `ec` claims the win. Claiming
637		the win requests stop on the operation's own stop token, which every
638		sibling observes through the stop token it was awaited with. A child
639		that await-returns a non-zero `ec`, or that exits via an exception,
640		does not claim the win and does not request stop. The operation keeps
641		waiting for a success. A stop request on the caller's stop token is
642		also forwarded to every child.
643
644		The await completes only after every child has finished, regardless of
645		whether a win was claimed.
646
647		@par Await-returns
648		An object of type
649		`std::variant<std::error_code, std::pair<std::size_t, PayloadT>>`,
650		where `PayloadT` is the payload of one child's `io_result`.
651
652		@li Index 1 holds the winner's position in the input range paired
653		with its payload.
654		@li Index 0 holds a non-zero `error_code` when no child won, that is,
655		when every child failed. It is the `ec` of one of the failed
656		children; which one is unspecified.
657
658		A child that succeeds after the win has already been claimed
659		contributes nothing: its payload is discarded.
660
661		If no child won and the failure selected for reporting is an
662		exception rather than an `ec`, that exception is rethrown instead of
663		await-returning. The choice of child is unspecified.
664
665		@par Await-postcondition
666		Every child has finished. If at least one child await-returned a zero
667		`ec`, the result holds index 1. If producing the winner's payload
668		threw, that exception is rethrown. Otherwise the result holds index 0,
669		or a failed child's exception is rethrown.
670
671		@par Remarks
672		Supports _IoAwaitable cancellation_. A canceled child await-returns a
673		non-zero `ec` and so cannot win; if no child has already succeeded,
674		the result settles at index 0.
675
676		@par Thread Safety
677		The returned task must be awaited from a single execution context.
678		Child awaitables execute concurrently but complete through the caller's
679		executor.
680
681		@param awaitables Range of io_result-returning awaitables (must
682		not be empty).
683
684		@return A task yielding variant<error_code, pair<size_t, PayloadT>>
685		where index 0 is failure and index 1 carries the winner's
686		index and payload.
687
688		@throws std::invalid_argument if range is empty.
689
690		@par Exception Safety
691		The winner's exception is rethrown if extracting or
692		move-constructing the winning payload throws. In that case a winner
693		was found, but its result could not be produced. If all children
694		fail and the reported failure is an exception, that child's
695		exception is rethrown (which child is unspecified).
696
697		@par Example
698		@par !example example_1
699
700
701		@see IoAwaitableRange, when_any
702		*/
703		template<IoAwaitableRange R>
704		requires detail::is_io_result_v<
705		awaitable_result_t<std::ranges::range_value_t<R>>>
706		&& (!std::is_same_v<
707		detail::io_result_payload_t<
708		awaitable_result_t<std::ranges::range_value_t<R>>>,
709		std::tuple<>>)
710	14x	[[nodiscard]] auto when_any(R&& awaitables)
711		-> task<std::variant<std::error_code,
712		std::pair<std::size_t,
713		detail::io_result_payload_t<
714		awaitable_result_t<std::ranges::range_value_t<R>>>>>>
715		{
716		using Awaitable = std::ranges::range_value_t<R>;
717		using PayloadT = detail::io_result_payload_t<
718		awaitable_result_t<Awaitable>>;
719		using result_type = std::variant<std::error_code,
720		std::pair<std::size_t, PayloadT>>;
721		using OwnedRange = std::remove_cvref_t<R>;
722
723		auto count = std::ranges::size(awaitables);
724		if(count == 0)
725		throw std::invalid_argument("when_any requires at least one awaitable");
726
727		OwnedRange owned_awaitables = std::forward<R>(awaitables);
728
729		detail::when_any_io_homogeneous_state<PayloadT> state(count);
730
731		co_await detail::when_any_io_homogeneous_launcher<OwnedRange>(
732		&owned_awaitables, &state);
733
734		// Winner found
735		if(state.core_.has_winner_.load(std::memory_order_acquire))
736		{
737		if(state.core_.winner_exception_)
738		std::rethrow_exception(state.core_.winner_exception_);
739		co_return result_type{std::in_place_index<1>,
740		std::pair{state.core_.winner_index_, std::move(*state.result_)}};
741		}
742
743		// No winner — report the recorded failure
744		if(state.last_exception_)
745		std::rethrow_exception(state.last_exception_);
746		co_return result_type{std::in_place_index<0>, state.last_error_};
747	28x	}
748
749		/** Race a range of void io_result-returning awaitables.
750
751		Only a child returning !ec can win. Returns the winner's index
752		at variant index 1, or error_code at index 0 on all-fail.
753
754		@par Await-effects
755
756		Takes ownership of the range, creates one wrapper coroutine per
757		element, then posts every wrapper to the caller's executor. All
758		children therefore run concurrently, each awaited with the caller's
759		executor and frame allocator and with a stop token owned by this
760		operation.
761
762		Awaiting an empty range throws `std::invalid_argument` before any
763		child is started.
764
765		The first child to await-return a zero `ec` claims the win. Claiming
766		the win requests stop on the operation's own stop token, which every
767		sibling observes through the stop token it was awaited with. A child
768		that await-returns a non-zero `ec`, or that exits via an exception,
769		does not claim the win and does not request stop. The operation keeps
770		waiting for a success. A stop request on the caller's stop token is
771		also forwarded to every child.
772
773		The await completes only after every child has finished, regardless of
774		whether a win was claimed.
775
776		@par Await-returns
777		An object of type `std::variant<std::error_code, std::size_t>`.
778
779		@li Index 1 holds the winner's position in the input range. The
780		children have no payloads, so nothing else is reported.
781		@li Index 0 holds a non-zero `error_code` when no child won, that is,
782		when every child failed. It is the `ec` of one of the failed
783		children; which one is unspecified.
784
785		If no child won and the failure selected for reporting is an
786		exception rather than an `ec`, that exception is rethrown instead of
787		await-returning. The choice of child is unspecified.
788
789		@par Await-postcondition
790		Every child has finished. The result holds index 1 if at least one
791		child await-returned a zero `ec`. Otherwise the result holds index 0,
792		or a failed child's exception is rethrown.
793
794		@par Remarks
795		Supports _IoAwaitable cancellation_. A canceled child await-returns a
796		non-zero `ec` and so cannot win; if no child has already succeeded,
797		the result settles at index 0.
798
799		@par Thread Safety
800		The returned task must be awaited from a single execution context.
801		Child awaitables execute concurrently but complete through the caller's
802		executor.
803
804		@param awaitables Range of io_result<>-returning awaitables (must
805		not be empty).
806
807		@return A task yielding variant<error_code, size_t> where index 0
808		is failure and index 1 carries the winner's index.
809
810		@throws std::invalid_argument if range is empty.
811
812		@par Exception Safety
813		If all children fail and the reported failure is an exception,
814		that child's exception is rethrown (which child is unspecified).
815
816		@par Example
817		@par !example example_2
818
819
820		@see IoAwaitableRange, when_any
821		*/
822		template<IoAwaitableRange R>
823		requires detail::is_io_result_v<
824		awaitable_result_t<std::ranges::range_value_t<R>>>
825		&& std::is_same_v<
826		detail::io_result_payload_t<
827		awaitable_result_t<std::ranges::range_value_t<R>>>,
828		std::tuple<>>
829	3x	[[nodiscard]] auto when_any(R&& awaitables)
830		-> task<std::variant<std::error_code, std::size_t>>
831		{
832		using OwnedRange = std::remove_cvref_t<R>;
833		using result_type = std::variant<std::error_code, std::size_t>;
834
835		auto count = std::ranges::size(awaitables);
836		if(count == 0)
837		throw std::invalid_argument("when_any requires at least one awaitable");
838
839		OwnedRange owned_awaitables = std::forward<R>(awaitables);
840
841		detail::when_any_io_homogeneous_state<std::tuple<>> state(count);
842
843		co_await detail::when_any_io_homogeneous_launcher<OwnedRange>(
844		&owned_awaitables, &state);
845
846		// Winner found
847		if(state.core_.has_winner_.load(std::memory_order_acquire))
848		{
849		if(state.core_.winner_exception_)
850		std::rethrow_exception(state.core_.winner_exception_);
851		co_return result_type{std::in_place_index<1>,
852		state.core_.winner_index_};
853		}
854
855		// No winner — report the recorded failure
856		if(state.last_exception_)
857		std::rethrow_exception(state.last_exception_);
858		co_return result_type{std::in_place_index<0>, state.last_error_};
859	6x	}
860
861		/** Race io_result-returning awaitables, selecting the first success.
862
863		Overload selected when all children return io_result<Ts...>.
864		Only a child returning !ec can win. Errors and exceptions do
865		not claim winner status.
866
867		@par Await-effects
868
869		Creates and posts one wrapper coroutine per argument to the caller's
870		executor, in argument order. All children therefore run concurrently,
871		each awaited with the caller's executor and frame allocator and with
872		a stop token owned by this operation. The overload requires at least
873		one awaitable, so there is no empty case.
874
875		The first child to await-return a zero `ec` claims the win. Claiming
876		the win requests stop on the operation's own stop token, which every
877		sibling observes through the stop token it was awaited with. A child
878		that await-returns a non-zero `ec`, or that exits via an exception,
879		does not claim the win and does not request stop. The operation keeps
880		waiting for a success. A stop request on the caller's stop token is
881		also forwarded to every child.
882
883		The await completes only after every child has finished, regardless of
884		whether a win was claimed.
885
886		@par Await-returns
887		An object of type `std::variant<std::error_code, P1, ..., Pn>`, where
888		`Pi` is the payload of the i-th child's `io_result`.
889
890		@li Index i+1 identifies the i-th argument as the winner and holds
891		its payload.
892		@li Index 0 holds a non-zero `error_code` when no child won, that is,
893		when every child failed. It is the `ec` of one of the failed
894		children; which one is unspecified.
895
896		A child that succeeds after the win has already been claimed
897		contributes nothing: its payload is discarded.
898
899		If no child won and the failure selected for reporting is an
900		exception rather than an `ec`, that exception is rethrown instead of
901		await-returning. The choice of child is unspecified.
902
903		@par Await-postcondition
904		Every child has finished. If at least one child await-returned a zero
905		`ec`, the result holds the index of the winning child. If producing
906		the winner's payload threw, that exception is rethrown. Otherwise the
907		result holds index 0, or a failed child's exception is rethrown.
908
909		@par Remarks
910		Supports _IoAwaitable cancellation_. A canceled child await-returns a
911		non-zero `ec` and so cannot win; if no child has already succeeded,
912		the result settles at index 0.
913
914		@par Thread Safety
915		The returned task must be awaited from a single execution context.
916		Child awaitables execute concurrently but complete through the caller's
917		executor.
918
919		@param as The awaitables to race. Each must satisfy @ref
920		IoAwaitable and is consumed (moved-from) when `when_any`
921		is awaited.
922
923		@return A task yielding variant<error_code, R1, ..., Rn> where
924		index 0 is the failure/no-winner case and index i+1
925		identifies the winning child. On all-fail, index 0 holds
926		an error_code from one of the failed children (unspecified
927		which; no priority between errors and exceptions).
928
929		@par Exception Safety
930		The winner's exception is rethrown if extracting or constructing
931		the winning payload throws. In that case a winner was found, but
932		its result could not be produced. If all children fail and the
933		reported failure is an exception, that child's exception is
934		rethrown (which child is unspecified).
935
936		@note A failing child does not cancel its siblings; `when_any`
937		waits for a success or for every child to finish. To make a
938		benign error (e.g. @c cond::canceled) count as a win, wrap
939		the child to translate the error into success. See the
940		Concurrent Composition tutorial.
941		*/
942		template<IoAwaitable... As>
943		requires (sizeof...(As) > 0)
944		&& detail::all_io_result_awaitables<As...>
945	23x	[[nodiscard]] auto when_any(As... as)
946		-> task<std::variant<
947		std::error_code,
948		detail::io_result_payload_t<awaitable_result_t<As>>...>>
949		{
950		using result_type = std::variant<
951		std::error_code,
952		detail::io_result_payload_t<awaitable_result_t<As>>...>;
953
954		detail::when_any_io_state<
955		detail::io_result_payload_t<awaitable_result_t<As>>...> state;
956		std::tuple<As...> awaitable_tuple(std::move(as)...);
957
958		co_await detail::when_any_io_launcher<As...>(
959		&awaitable_tuple, &state);
960
961		// Winner found: return their result
962		if(state.result_.has_value())
963		co_return std::move(*state.result_);
964
965		// Winner claimed but payload construction failed
966		if(state.core_.winner_exception_)
967		std::rethrow_exception(state.core_.winner_exception_);
968
969		// No winner — report the recorded failure
970		if(state.last_exception_)
971		std::rethrow_exception(state.last_exception_);
972		co_return result_type{std::in_place_index<0>, state.last_error_};
973	46x	}
974
975		} // namespace capy
976		} // namespace boost
977
978		#endif
979