include/boost/capy/ex/run_async.hpp

100.0% Lines (210 / 210, 2 excl) 97.4% Functions (5207 / 5348, 296 excl)

[ ] prev/next file

run_async.hpp

f(x) Functions (5644)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3		// Copyright (c) 2026 Michael Vandeberg
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_RUN_ASYNC_HPP
12		#define BOOST_CAPY_RUN_ASYNC_HPP
13
14		#include <boost/capy/detail/config.hpp>
15		#include <boost/capy/detail/run.hpp>
16		#include <boost/capy/detail/run_callbacks.hpp>
17		#include <boost/capy/concept/executor.hpp>
18		#include <boost/capy/concept/context_runnable.hpp>
19		#include <boost/capy/ex/abandon.hpp>
20		#include <boost/capy/ex/execution_context.hpp>
21		#include <boost/capy/ex/frame_allocator.hpp>
22		#include <boost/capy/ex/await_context.hpp>
23		#include <boost/capy/ex/recycling_memory_resource.hpp>
24		#include <boost/capy/ex/work_guard.hpp>
25
26		#include <coroutine>
27		#include <cstring>
28		#include <exception>
29		#include <memory_resource>
30		#include <new>
31		#include <stop_token>
32		#include <type_traits>
33
34		namespace boost {
35		namespace capy {
36		namespace detail {
37
38		/** Match types usable as `run_async` completion handlers.
39
40		Excludes the types meaningful to the other `run_async` parameters.
41		A stop token, memory resource pointer, or allocator argument
42		therefore selects its dedicated overload by conversion. It does not
43		deduce as an exact-match handler.
44		*/
45		template<class H>
46		concept RunAsyncHandler =
47		!std::is_convertible_v<H, std::pmr::memory_resource*> &&
48		!std::is_convertible_v<H, std::stop_token> &&
49		!Allocator<H>;
50
51		/// Function pointer type for type-erased frame deallocation.
52		using dealloc_fn = void()(void, std::size_t);
53
54		/// Type-erased deallocator implementation for trampoline frames.
55		template<class Alloc>
56	2327x	void dealloc_impl(void* raw, std::size_t total)
57		{
58		static_assert(std::is_same_v<typename Alloc::value_type, frame_unit>);
59	2327x	auto* a = std::launder(reinterpret_cast<Alloc*>(
60	2327x	static_cast<char*>(raw) + total - sizeof(Alloc)));
61	2327x	Alloc ua(std::move(*a));
62	18x	a->~Alloc();
63	2327x	ua.deallocate(static_cast<frame_unit*>(raw), frame_units(total));
64	2327x	}
65
66		/// Awaiter to access the promise from within the coroutine.
67		template<class Promise>
68		struct get_promise_awaiter
69		{
70		Promise* p_ = nullptr;
71
72	5819x	bool await_ready() const noexcept { return false; }
73
74	5819x	bool await_suspend(std::coroutine_handle<Promise> h) noexcept
75		{
76	5819x	p_ = &h.promise();
77	5819x	return false;
78		}
79
80	5819x	Promise& await_resume() const noexcept
81		{
82	5819x	return *p_;
83		}
84		};
85
86		/** Internal run_async_trampoline coroutine for run_async.
87
88		The run_async_trampoline is allocated BEFORE the task (via C++17 postfix evaluation
89		order) and serves as the task's continuation. When the task final_suspends,
90		control returns to the run_async_trampoline which then invokes the appropriate handler.
91
92		For value-type allocators, the run_async_trampoline stores a frame_memory_resource
93		that wraps the allocator. For memory_resource*, it stores the pointer directly.
94
95		@tparam Ex The executor type.
96		@tparam Handlers The handler type (default_handler or handler_pair).
97		@tparam Alloc The allocator type (value type or memory_resource*).
98		*/
99		template<class Ex, class Handlers, class Alloc>
100		struct run_async_trampoline
101		{
102		using invoke_fn = void()(void, Handlers&);
103
104		struct promise_type
105		{
106		work_guard<Ex> wg_;
107		Handlers handlers_;
108		frame_memory_resource<Alloc> resource_;
109		await_context env_;
110		invoke_fn invoke_ = nullptr;
111		void* task_promise_ = nullptr;
112		// task_h_: raw handle for frame_guard cleanup in make_trampoline.
113		// task_cont_: continuation wrapping the same handle for executor dispatch.
114		// Both must reference the same coroutine and be kept in sync.
115		std::coroutine_handle<> task_h_;
116		continuation task_cont_;
117		// Owns the task's segment: abandoning it resumes this
118		// trampoline, or has it destroyed, to unwind the task.
119		chain_owner owner_;
120
121	2327x	~promise_type()
122		{
123		// Still owned only when a closed executor destroyed this
124		// trampoline instead of resuming it to unwind the task.
125	2327x	if(task_h_)
126	7x	task_h_.destroy();
127	2327x	}
128
129	2327x	promise_type(Ex& ex, Handlers& h, Alloc& a) noexcept
130	2327x	: wg_(std::move(ex))
131	2327x	, handlers_(std::move(h))
132	2327x	, resource_(std::move(a))
133		{
134	2327x	}
135
136		// Allocates whole frame units: a standard allocator takes no
137		// alignment argument, and one rebound to std::byte may place
138		// this frame at byte alignment.
139		using unit_alloc = typename std::allocator_traits<Alloc>
140		::template rebind_alloc<frame_unit>;
141
142		static_assert(
143		alignof(unit_alloc) <= frame_alignment,
144		"Alloc must not be over-aligned");
145
146		static constexpr std::size_t
147	13962x	round_up(std::size_t n, std::size_t align) noexcept
148		{
149	13962x	return (n + align - 1) & ~(align - 1);
150		}
151
152		// The block holds the frame, then the deallocator, then the
153		// allocator copy, each at its own alignment. The copy comes
154		// last, where dealloc_impl looks for it.
155		static constexpr std::size_t
156	9308x	fn_offset(std::size_t size) noexcept
157		{
158	9308x	return round_up(size, alignof(dealloc_fn));
159		}
160
161		static constexpr std::size_t
162	4654x	block_size(std::size_t size) noexcept
163		{
164	4654x	return round_up(
165	4654x	fn_offset(size) + sizeof(dealloc_fn),
166	4654x	alignof(unit_alloc)) + sizeof(unit_alloc);
167		}
168
169	2327x	static void* operator new(
170		std::size_t size, Ex const&, Handlers const&, Alloc a)
171		{
172	2327x	auto const total = block_size(size);
173
174	18x	unit_alloc ua(std::move(a));
175	2327x	void* raw = ua.allocate(frame_units(total));
176
177	2327x	auto* fn_loc = reinterpret_cast<dealloc_fn*>(
178	2327x	static_cast<char*>(raw) + fn_offset(size));
179	2327x	*fn_loc = &dealloc_impl<unit_alloc>;
180
181	2343x	new (static_cast<char*>(raw) + total - sizeof(unit_alloc))
182	2327x	unit_alloc(std::move(ua));
183
184	6945x	return raw;
185	15x	}
186
187	2327x	static void operator delete(void* ptr, std::size_t size)
188		{
189	2327x	auto* fn = reinterpret_cast<dealloc_fn*>(
190	2327x	static_cast<char*>(ptr) + fn_offset(size));
191	2327x	(*fn)(ptr, block_size(size));
192	2327x	}
193
194	4654x	std::pmr::memory_resource* get_resource() noexcept
195		{
196	4654x	return &resource_;
197		}
198
199	2327x	run_async_trampoline get_return_object() noexcept
200		{
201		return run_async_trampoline{
202	2327x	std::coroutine_handle<promise_type>::from_promise(*this)};
203		}
204
205	2327x	std::suspend_always initial_suspend() noexcept
206		{
207	2327x	return {};
208		}
209
210	2320x	std::suspend_never final_suspend() noexcept
211		{
212	2320x	return {};
213		}
214
215	2320x	void return_void() noexcept
216		{
217	2320x	}
218
219		// An exception reaches here only by escaping a handler: a handler
220		// that threw, or the default handler rethrowing an otherwise
221		// unhandled task exception. Cancellation is filtered out earlier
222		// by default_handler, so this is always a genuine error with no
223		// owner to receive it: fail fast.
224	−	void unhandled_exception() noexcept { std::terminate(); } // LCOV_EXCL_LINE
225		};
226
227		std::coroutine_handle<promise_type> h_;
228
229		template<ContextRunnable Task>
230	2306x	static void invoke_impl(void* p, Handlers& h)
231		{
232		using R = decltype(std::declval<Task&>().await_resume());
233	2306x	auto& promise = static_cast<typename Task::promise_type>(p);
234	2306x	if(promise.exception())
235	1x	h(promise.exception());
236		else if constexpr(std::is_void_v<R>)
237	2302x	h();
238		else
239	3x	h(std::move(promise.result()));
240	2306x	}
241		};
242
243		/** Specialization for memory_resource* - stores pointer directly.
244
245		This avoids double indirection when the user passes a memory_resource*.
246		*/
247		template<class Ex, class Handlers>
248		struct run_async_trampoline<Ex, Handlers, std::pmr::memory_resource*>
249		{
250		using invoke_fn = void()(void, Handlers&);
251
252		struct promise_type
253		{
254		work_guard<Ex> wg_;
255		Handlers handlers_;
256		std::pmr::memory_resource* mr_;
257		await_context env_;
258		invoke_fn invoke_ = nullptr;
259		void* task_promise_ = nullptr;
260		// task_h_: raw handle for frame_guard cleanup in make_trampoline.
261		// task_cont_: continuation wrapping the same handle for executor dispatch.
262		// Both must reference the same coroutine and be kept in sync.
263		std::coroutine_handle<> task_h_;
264		continuation task_cont_;
265		// Owns the task's segment: abandoning it resumes this
266		// trampoline, or has it destroyed, to unwind the task.
267		chain_owner owner_;
268
269	103688x	~promise_type()
270		{
271		// Still owned only when a closed executor destroyed this
272		// trampoline instead of resuming it to unwind the task.
273	103688x	if(task_h_)
274	100188x	task_h_.destroy();
275	103688x	}
276
277	103688x	promise_type(
278		Ex& ex, Handlers& h, std::pmr::memory_resource* mr) noexcept
279	103688x	: wg_(std::move(ex))
280	103688x	, handlers_(std::move(h))
281	103688x	, mr_(mr)
282		{
283	103688x	}
284
285	103688x	static void* operator new(
286		std::size_t size, Ex const&, Handlers const&,
287		std::pmr::memory_resource* mr)
288		{
289	103688x	auto total = size + sizeof(mr);
290	103688x	void* raw = mr->allocate(total, frame_alignment);
291	103688x	std::memcpy(static_cast<char*>(raw) + size, &mr, sizeof(mr));
292	103688x	return raw;
293		}
294
295	103688x	static void operator delete(void* ptr, std::size_t size)
296		{
297		std::pmr::memory_resource* mr;
298	103688x	std::memcpy(&mr, static_cast<char*>(ptr) + size, sizeof(mr));
299	103688x	auto total = size + sizeof(mr);
300	103688x	mr->deallocate(ptr, total, frame_alignment);
301	103688x	}
302
303	207375x	std::pmr::memory_resource* get_resource() noexcept
304		{
305	207375x	return mr_;
306		}
307
308	103688x	run_async_trampoline get_return_object() noexcept
309		{
310		return run_async_trampoline{
311	103688x	std::coroutine_handle<promise_type>::from_promise(*this)};
312		}
313
314	103688x	std::suspend_always initial_suspend() noexcept
315		{
316	103688x	return {};
317		}
318
319	3499x	std::suspend_never final_suspend() noexcept
320		{
321	3499x	return {};
322		}
323
324	3499x	void return_void() noexcept
325		{
326	3499x	}
327
328		// See primary template: an escaping handler exception is fatal.
329	−	void unhandled_exception() noexcept { std::terminate(); } // LCOV_EXCL_LINE
330		};
331
332		std::coroutine_handle<promise_type> h_;
333
334		template<ContextRunnable Task>
335	2371x	static void invoke_impl(void* p, Handlers& h)
336		{
337		using R = decltype(std::declval<Task&>().await_resume());
338	2371x	auto& promise = static_cast<typename Task::promise_type>(p);
339	2371x	if(promise.exception())
340	377x	h(promise.exception());
341		else if constexpr(std::is_void_v<R>)
342	1706x	h();
343		else
344	288x	h(std::move(promise.result()));
345	2371x	}
346		};
347
348		/// Coroutine body for run_async_trampoline - invokes handlers then destroys task.
349		template<class Ex, class Handlers, class Alloc>
350		run_async_trampoline<Ex, Handlers, Alloc>
351	106015x	make_trampoline(Ex, Handlers, Alloc)
352		{
353		// promise_type ctor steals the parameters
354		auto& p = co_await get_promise_awaiter<
355		typename run_async_trampoline<Ex, Handlers, Alloc>::promise_type>{};
356
357		// Guard ensures the task frame is destroyed even when invoke_
358		// throws (e.g. default_handler rethrows an unhandled exception).
359		struct frame_guard
360		{
361		std::coroutine_handle<>& h;
362	509x	~frame_guard() { std::exchange(h, nullptr).destroy(); }
363		} guard{p.task_h_};
364
365		// Resumed with the task unfinished: the segment was abandoned, and
366		// destroying the task unwinds it without calling a handler.
367		if(!p.owner_.abandoned())
368		p.invoke_(p.task_promise_, p.handlers_);
369	216648x	}
370
371		} // namespace detail
372
373		/** Installs the frame allocator, then starts the task on the executor when called once.
374
375		This wrapper holds the run_async_trampoline coroutine, executor, stop token,
376		and handlers. The run_async_trampoline is allocated when the wrapper is constructed
377		(before the task due to C++17 postfix evaluation order).
378
379		The rvalue ref-qualifier on `operator()` ensures the wrapper can only
380		be used as a temporary, preventing misuse that would violate LIFO ordering.
381
382		@tparam Ex The executor type satisfying the `Executor` concept.
383		@tparam Handlers The handler type (default_handler or handler_pair).
384		@tparam Alloc The allocator type (value type or memory_resource*).
385
386		@par Thread Safety
387		The wrapper itself should only be used from one thread. The handlers
388		may be invoked from any thread where the executor schedules work.
389
390		@warning **Always construct the task as the direct argument of the
391		two-call expression `run_async(ex)(task)`.** The wrapper's constructor
392		installs the frame allocator in thread-local storage. The task's
393		`operator new` reads that thread-local state. Splitting the two calls
394		apart in any of the following ways allocates the task's coroutine
395		frame under the wrong allocator. Each does so silently, with no
396		compile error.
397		@li Stored wrapper. Storing the wrapper itself
398		(`auto w = run_async(ex);`) compiles fine. C++17 guaranteed copy
399		elision constructs `w` directly from the prvalue. The deleted
400		copy/move constructors are never considered. What the rvalue
401		ref-qualifier on `operator()` rejects is calling through that
402		stored lvalue: `w(my_task())` does not compile, and
403		`std::move(w)(my_task())` is required instead. The silent
404		variant is storing the task
405		(`auto t = my_task(); run_async(ex)(std::move(t));`): `t`'s frame
406		is allocated before `run_async(ex)` ever runs.
407		@li Preconstructed task. Passing an already-constructed task object
408		has the same effect as the stored-wrapper case. So does passing a
409		moved-from local, or a task returned from an earlier statement.
410		The frame exists before the allocator is installed.
411		@li Wrapper function. Forwarding the task through a helper that
412		itself performs the two-call pattern constructs the task as an
413		argument to the helper. It is therefore constructed before the
414		helper's body runs, and so before `run_async` runs. An example is
415		`submit(ex, my_task())`, where `submit` calls
416		`run_async(ex)(std::forward<Task>(t))` internally.
417
418		See the Frame Allocators guide
419		(`doc/modules/ROOT/pages/4.coroutines/4g.allocators.adoc`) for the full
420		C++17-evaluation-order rationale behind this constraint.
421
422		@par Example
423		@par !example example
424
425
426		@see @ref run_async
427		*/
428		template<Executor Ex, class Handlers, class Alloc>
429		class [[nodiscard]] run_async_wrapper
430		{
431		detail::run_async_trampoline<Ex, Handlers, Alloc> tr_;
432		std::stop_token st_;
433		std::pmr::memory_resource* saved_tls_;
434
435		public:
436		/** Construct the wrapper and install the frame allocator.
437
438		Builds the trampoline and saves the current thread-local frame
439		allocator. Then installs the trampoline's resource as the new
440		thread-local allocator. The task frame, evaluated as the argument
441		to @ref operator(), is therefore allocated from that resource.
442
443		@param ex The executor on which the task runs.
444		@param st The stop token for cooperative cancellation.
445		@param h The completion handlers.
446		@param a The allocator for frame allocation.
447
448		@note When `Alloc` is not `std::pmr::memory_resource*` it must be
449		nothrow move constructible (enforced by a `static_assert`), which
450		is what allows this constructor to be `noexcept`. If allocating
451		the launch state throws, `std::terminate` is called.
452		*/
453	106015x	run_async_wrapper(
454		Ex ex,
455		std::stop_token st,
456		Handlers h,
457		Alloc a) noexcept
458	107153x	: tr_(detail::make_trampoline<Ex, Handlers, Alloc>(
459	109462x	std::move(ex), std::move(h), std::move(a)))
460	106015x	, st_(std::move(st))
461	106015x	, saved_tls_(get_current_frame_allocator())
462		{
463		if constexpr (!std::is_same_v<Alloc, std::pmr::memory_resource*>)
464		{
465		static_assert(
466		std::is_nothrow_move_constructible_v<Alloc>,
467		"Allocator must be nothrow move constructible");
468		}
469		// Set TLS before task argument is evaluated
470	106015x	set_current_frame_allocator(tr_.h_.promise().get_resource());
471	106015x	}
472
473		/** Restore the previously installed frame allocator.
474
475		Resets the thread-local frame allocator to the value saved at
476		construction. A stale pointer to the trampoline's resource
477		therefore does not outlive the execution context that owns it.
478		If no task was started, for example because evaluating the task
479		argument threw, the unused launch state is destroyed, releasing
480		the executor's work.
481		*/
482	106015x	~run_async_wrapper()
483		{
484	106015x	if(tr_.h_)
485	2x	tr_.h_.destroy();
486	106015x	set_current_frame_allocator(saved_tls_);
487	106015x	}
488
489		// Non-copyable, non-movable (must be used immediately)
490
491		/** Copy construction is disabled; the wrapper must be used immediately.
492
493		@param other The wrapper that would be copied.
494		*/
495		run_async_wrapper(run_async_wrapper const& other) = delete;
496
497		/** Move construction is disabled; the wrapper must be used immediately.
498
499		@param other The wrapper that would be moved from.
500		*/
501		run_async_wrapper(run_async_wrapper&& other) = delete;
502
503		/** Copy assignment is disabled; the wrapper must be used immediately.
504
505		@param other The wrapper that would be assigned from.
506
507		@return A reference to `*this`.
508		*/
509		run_async_wrapper& operator=(run_async_wrapper const& other) = delete;
510
511		/** Move assignment is disabled; the wrapper must be used immediately.
512
513		@param other The wrapper that would be moved from.
514
515		@return A reference to `*this`.
516		*/
517		run_async_wrapper& operator=(run_async_wrapper&& other) = delete;
518
519		/** Start the task for execution.
520
521		This operator accepts a task and starts it on the executor.
522		The rvalue ref-qualifier ensures the wrapper is consumed, enforcing
523		correct LIFO destruction order.
524
525		The `await_context` constructed for the task is owned by the trampoline
526		coroutine and is guaranteed to outlive the task and all awaitables
527		in its chain. Awaitables may store `await_context const*` without concern
528		for dangling references.
529
530		@throws Any exception thrown by the executor's `dispatch`. The
531		task is then destroyed without running, and the executor's
532		work is released.
533
534		@tparam Task The ContextRunnable type.
535
536		@param t The task to execute. Ownership is transferred to the
537		run_async_trampoline which destroys it after completion.
538		*/
539		template<ContextRunnable Task>
540	106014x	void operator()(Task t) &&
541		{
542	106014x	auto task_h = t.handle();
543	106014x	auto& task_promise = task_h.promise();
544	106014x	t.release();
545
546	106014x	auto& p = tr_.h_.promise();
547
548		// Inject Task-specific invoke function
549	106014x	p.invoke_ = detail::run_async_trampoline<Ex, Handlers, Alloc>::template invoke_impl<Task>;
550	106014x	p.task_promise_ = &task_promise;
551	106014x	p.task_h_ = task_h;
552
553		// Setup task's continuation to return to run_async_trampoline
554	106014x	task_promise.set_continuation(tr_.h_);
555	106014x	p.owner_.bind(tr_.h_, p.wg_.executor());
556	212028x	p.env_ = {p.wg_.executor(), st_, p.get_resource(), &p.owner_};
557	106014x	task_promise.set_environment(&p.env_);
558
559		// Start task through executor.
560		// safe_resume is not needed here: TLS is already saved in the
561		// constructor (saved_tls_) and restored in the destructor.
562	106014x	p.task_cont_.h = task_h;
563	106014x	p.task_cont_.owner = &p.owner_;
564		// If dispatch throws, the destructor destroys the trampoline
565		// and the unstarted task with it.
566	106014x	auto next = p.wg_.executor().dispatch(p.task_cont_);
567		// From here the trampoline destroys itself when the task ends.
568	106013x	tr_.h_ = nullptr;
569	106013x	next.resume();
570	212027x	}
571		};
572
573		// Executor only (uses default recycling allocator)
574
575		/** Bind an executor to produce a launcher. Invoke the launcher with a task to start it.
576
577		Use this to start execution of a `task<T>` that was created lazily.
578		The returned wrapper must be immediately invoked with the task;
579		storing the wrapper and calling it later violates LIFO ordering.
580
581		Uses the default recycling frame allocator for coroutine frames.
582		With no handlers, the result is discarded. An unhandled exception
583		thrown by the task calls `std::terminate`. To catch it instead, pass
584		an error handler that receives it as an `exception_ptr`, or `co_await`
585		the work inside a coroutine.
586
587		Construct the task as the direct argument of the two-call expression
588		`run_async(ex)(task)`.
589
590		@par Thread Safety
591		The wrapper itself should only be used from one thread.
592
593		@par Example
594		@par !example example_1
595
596
597		@param ex The executor to execute the task on.
598
599		@return A wrapper that accepts a `task<T>` for immediate execution.
600
601		@see @ref task
602		@see @ref Executor
603		@see @ref run_async_wrapper
604		*/
605		template<Executor Ex>
606		[[nodiscard]] auto
607	101425x	run_async(Ex ex)
608		{
609	101425x	auto* mr = ex.context().get_frame_allocator();
610		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
611	101425x	std::move(ex),
612	202850x	std::stop_token{},
613		detail::default_handler{},
614	101425x	mr);
615		}
616
617		/** Bind an executor and a result handler to produce a launcher. Invoke the launcher with a task to start it.
618
619		The handler `h1` is called with the task's result on success. If `h1`
620		is also invocable with `std::exception_ptr`, it handles exceptions too.
621		Otherwise, an unhandled exception calls `std::terminate`.
622		If the task is abandoned before it completes, as a context's teardown
623		does, no handler is called; the handlers are destroyed with it.
624
625		Construct the task as the direct argument of the two-call expression
626		`run_async(ex)(task)`.
627
628		@par Thread Safety
629		The wrapper itself should only be used from one thread. The handlers
630		may be invoked from any thread where the executor schedules work.
631
632		@par Example
633		@par !example example_2
634
635
636		@param ex The executor to execute the task on.
637		@param h1 The handler to invoke with the result (and optionally exception).
638
639		@return A wrapper that accepts a `task<T>` for immediate execution.
640
641		@see @ref task
642		@see @ref Executor
643		@see @ref run_async_wrapper
644		*/
645		template<Executor Ex, class H1>
646		requires detail::RunAsyncHandler<H1>
647		[[nodiscard]] auto
648	115x	run_async(Ex ex, H1 h1)
649		{
650	115x	auto* mr = ex.context().get_frame_allocator();
651		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
652	115x	std::move(ex),
653	122x	std::stop_token{},
654	108x	detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
655	223x	mr);
656		}
657
658		/** Bind an executor and separate result and error handlers to produce a launcher. Invoke the launcher with a task to start it.
659
660		The handler `h1` is called with the task's result on success.
661		The handler `h2` is called with the exception_ptr on failure.
662		If the task is abandoned before it completes, as a context's teardown
663		does, no handler is called; the handlers are destroyed with it.
664
665		Construct the task as the direct argument of the two-call expression
666		`run_async(ex)(task)`.
667
668		@par Thread Safety
669		The wrapper itself should only be used from one thread. The handlers
670		may be invoked from any thread where the executor schedules work.
671
672		@par Example
673		@par !example example_3
674
675
676		@param ex The executor to execute the task on.
677		@param h1 The handler to invoke with the result on success.
678		@param h2 The handler to invoke with the exception on failure.
679
680		@return A wrapper that accepts a `task<T>` for immediate execution.
681
682		@see @ref task
683		@see @ref Executor
684		@see @ref run_async_wrapper
685		*/
686		template<Executor Ex, class H1, class H2>
687		requires (detail::RunAsyncHandler<H1> && detail::RunAsyncHandler<H2>)
688		[[nodiscard]] auto
689	109x	run_async(Ex ex, H1 h1, H2 h2)
690		{
691	109x	auto* mr = ex.context().get_frame_allocator();
692		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
693	109x	std::move(ex),
694	112x	std::stop_token{},
695	106x	detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
696	215x	mr);
697	3x	}
698
699		// Ex + stop_token
700
701		/** Bind an executor and a stop token to produce a launcher. Invoke the launcher with a task to start it.
702
703		The stop token is propagated to the task, enabling cooperative
704		cancellation. With no handlers, the result is discarded and an
705		unhandled exception calls `std::terminate`.
706
707		Construct the task as the direct argument of the two-call expression
708		`run_async(ex)(task)`.
709
710		@par Thread Safety
711		The wrapper itself should only be used from one thread.
712
713		@par Example
714		@par !example example_4
715
716
717		@param ex The executor to execute the task on.
718		@param st The stop token for cooperative cancellation.
719
720		@return A wrapper that accepts a `task<T>` for immediate execution.
721
722		@see @ref task
723		@see @ref Executor
724		@see @ref run_async_wrapper
725		*/
726		template<Executor Ex>
727		[[nodiscard]] auto
728	378x	run_async(Ex ex, std::stop_token st)
729		{
730	378x	auto* mr = ex.context().get_frame_allocator();
731		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
732	378x	std::move(ex),
733	378x	std::move(st),
734		detail::default_handler{},
735	756x	mr);
736		}
737
738		/** Bind an executor, a stop token, and a result handler to produce a launcher. Invoke the launcher with a task to start it.
739
740		The stop token is propagated to the task for cooperative cancellation.
741		The handler `h1` is called with the result on success, and optionally
742		with exception_ptr if it accepts that type.
743
744		Construct the task as the direct argument of the two-call expression
745		`run_async(ex)(task)`.
746
747		@par Thread Safety
748		The wrapper itself should only be used from one thread. The handlers
749		may be invoked from any thread where the executor schedules work.
750
751		@param ex The executor to execute the task on.
752		@param st The stop token for cooperative cancellation.
753		@param h1 The handler to invoke with the result (and optionally exception).
754
755		@return A wrapper that accepts a `task<T>` for immediate execution.
756
757		@see @ref task
758		@see @ref Executor
759		@see @ref run_async_wrapper
760		*/
761		template<Executor Ex, class H1>
762		requires detail::RunAsyncHandler<H1>
763		[[nodiscard]] auto
764	1619x	run_async(Ex ex, std::stop_token st, H1 h1)
765		{
766	1619x	auto* mr = ex.context().get_frame_allocator();
767		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
768	1619x	std::move(ex),
769	1619x	std::move(st),
770	1619x	detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
771	3238x	mr);
772	1114x	}
773
774		/** Bind an executor, a stop token, and separate result and error handlers to produce a launcher. Invoke the launcher with a task to start it.
775
776		The stop token is propagated to the task for cooperative cancellation.
777		The handler `h1` is called on success, `h2` on failure.
778
779		Construct the task as the direct argument of the two-call expression
780		`run_async(ex)(task)`.
781
782		@par Thread Safety
783		The wrapper itself should only be used from one thread. The handlers
784		may be invoked from any thread where the executor schedules work.
785
786		@param ex The executor to execute the task on.
787		@param st The stop token for cooperative cancellation.
788		@param h1 The handler to invoke with the result on success.
789		@param h2 The handler to invoke with the exception on failure.
790
791		@return A wrapper that accepts a `task<T>` for immediate execution.
792
793		@see @ref task
794		@see @ref Executor
795		@see @ref run_async_wrapper
796		*/
797		template<Executor Ex, class H1, class H2>
798		requires (detail::RunAsyncHandler<H1> && detail::RunAsyncHandler<H2>)
799		[[nodiscard]] auto
800	20x	run_async(Ex ex, std::stop_token st, H1 h1, H2 h2)
801		{
802	20x	auto* mr = ex.context().get_frame_allocator();
803		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
804	20x	std::move(ex),
805	20x	std::move(st),
806	20x	detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
807	40x	mr);
808		}
809
810		// Ex + memory_resource*
811
812		/** Bind an executor and a memory resource to produce a launcher. Invoke the launcher with a task to start it.
813
814		The memory resource is used for coroutine frame allocation.
815
816		Construct the task as the direct argument of the two-call expression
817		`run_async(ex)(task)`.
818
819		@par Thread Safety
820		The wrapper itself should only be used from one thread.
821
822		@pre `mr` outlives every task started through the returned wrapper.
823
824		@param ex The executor to execute the task on.
825		@param mr The memory resource for frame allocation.
826
827		@return A wrapper that accepts a `task<T>` for immediate execution.
828
829		@see @ref task
830		@see @ref Executor
831		@see @ref run_async_wrapper
832		*/
833		template<Executor Ex>
834		[[nodiscard]] auto
835	16x	run_async(Ex ex, std::pmr::memory_resource* mr)
836		{
837		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
838	16x	std::move(ex),
839	32x	std::stop_token{},
840		detail::default_handler{},
841	16x	mr);
842		}
843
844		/** Bind an executor, a memory resource, and a result handler to produce a launcher. Invoke the launcher with a task to start it.
845
846		Construct the task as the direct argument of the two-call expression
847		`run_async(ex)(task)`.
848
849		@par Thread Safety
850		The wrapper itself should only be used from one thread. The handlers
851		may be invoked from any thread where the executor schedules work.
852
853		@pre `mr` outlives every task started through the returned wrapper.
854
855		@param ex The executor to execute the task on.
856		@param mr The memory resource for frame allocation.
857		@param h1 The handler to invoke with the result (and optionally exception).
858
859		@return A wrapper that accepts a `task<T>` for immediate execution.
860
861		@see @ref task
862		@see @ref Executor
863		@see @ref run_async_wrapper
864		*/
865		template<Executor Ex, class H1>
866		[[nodiscard]] auto
867	2x	run_async(Ex ex, std::pmr::memory_resource* mr, H1 h1)
868		{
869		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
870	2x	std::move(ex),
871	2x	std::stop_token{},
872	2x	detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
873	4x	mr);
874		}
875
876		/** Bind an executor, a memory resource, and separate result and error handlers to produce a launcher. Invoke the launcher with a task to start it.
877
878		Construct the task as the direct argument of the two-call expression
879		`run_async(ex)(task)`.
880
881		@par Thread Safety
882		The wrapper itself should only be used from one thread. The handlers
883		may be invoked from any thread where the executor schedules work.
884
885		@pre `mr` outlives every task started through the returned wrapper.
886
887		@param ex The executor to execute the task on.
888		@param mr The memory resource for frame allocation.
889		@param h1 The handler to invoke with the result on success.
890		@param h2 The handler to invoke with the exception on failure.
891
892		@return A wrapper that accepts a `task<T>` for immediate execution.
893
894		@see @ref task
895		@see @ref Executor
896		@see @ref run_async_wrapper
897		*/
898		template<Executor Ex, class H1, class H2>
899		[[nodiscard]] auto
900	2x	run_async(Ex ex, std::pmr::memory_resource* mr, H1 h1, H2 h2)
901		{
902		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
903	2x	std::move(ex),
904	2x	std::stop_token{},
905	2x	detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
906	4x	mr);
907	2x	}
908
909		// Ex + stop_token + memory_resource*
910
911		/** Bind an executor, a stop token, and a memory resource to produce a launcher. Invoke the launcher with a task to start it.
912
913		Construct the task as the direct argument of the two-call expression
914		`run_async(ex)(task)`.
915
916		@par Thread Safety
917		The wrapper itself should only be used from one thread.
918
919		@pre `mr` outlives every task started through the returned wrapper.
920
921		@param ex The executor to execute the task on.
922		@param st The stop token for cooperative cancellation.
923		@param mr The memory resource for frame allocation.
924
925		@return A wrapper that accepts a `task<T>` for immediate execution.
926
927		@see @ref task
928		@see @ref Executor
929		@see @ref run_async_wrapper
930		*/
931		template<Executor Ex>
932		[[nodiscard]] auto
933	1x	run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr)
934		{
935		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
936	1x	std::move(ex),
937	1x	std::move(st),
938		detail::default_handler{},
939	2x	mr);
940		}
941
942		/** Bind an executor, a stop token, a memory resource, and a result handler to produce a launcher. Invoke the launcher with a task to start it.
943
944		Construct the task as the direct argument of the two-call expression
945		`run_async(ex)(task)`.
946
947		@par Thread Safety
948		The wrapper itself should only be used from one thread. The handlers
949		may be invoked from any thread where the executor schedules work.
950
951		@pre `mr` outlives every task started through the returned wrapper.
952
953		@param ex The executor to execute the task on.
954		@param st The stop token for cooperative cancellation.
955		@param mr The memory resource for frame allocation.
956		@param h1 The handler to invoke with the result (and optionally exception).
957
958		@return A wrapper that accepts a `task<T>` for immediate execution.
959
960		@see @ref task
961		@see @ref Executor
962		@see @ref run_async_wrapper
963		*/
964		template<Executor Ex, class H1>
965		[[nodiscard]] auto
966		run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr, H1 h1)
967		{
968		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
969		std::move(ex),
970		std::move(st),
971		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
972		mr);
973		}
974
975		/** Bind an executor, a stop token, a memory resource, and separate result and error handlers to produce a launcher. Invoke the launcher with a task to start it.
976
977		Construct the task as the direct argument of the two-call expression
978		`run_async(ex)(task)`.
979
980		@par Thread Safety
981		The wrapper itself should only be used from one thread. The handlers
982		may be invoked from any thread where the executor schedules work.
983
984		@pre `mr` outlives every task started through the returned wrapper.
985
986		@param ex The executor to execute the task on.
987		@param st The stop token for cooperative cancellation.
988		@param mr The memory resource for frame allocation.
989		@param h1 The handler to invoke with the result on success.
990		@param h2 The handler to invoke with the exception on failure.
991
992		@return A wrapper that accepts a `task<T>` for immediate execution.
993
994		@see @ref task
995		@see @ref Executor
996		@see @ref run_async_wrapper
997		*/
998		template<Executor Ex, class H1, class H2>
999		[[nodiscard]] auto
1000	1x	run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr, H1 h1, H2 h2)
1001		{
1002		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
1003	1x	std::move(ex),
1004	1x	std::move(st),
1005		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
1006	2x	mr);
1007		}
1008
1009		// Ex + standard Allocator (value type)
1010
1011		/** Bind an executor and an allocator to produce a launcher. Invoke the launcher with a task to start it.
1012
1013		The allocator is wrapped in a frame_memory_resource and stored in the
1014		run_async_trampoline, ensuring it outlives all coroutine frames.
1015
1016		Construct the task as the direct argument of the two-call expression
1017		`run_async(ex)(task)`.
1018
1019		@par Thread Safety
1020		The wrapper itself should only be used from one thread.
1021
1022		@param ex The executor to execute the task on.
1023		@param alloc The allocator for frame allocation (copied and stored).
1024
1025		@return A wrapper that accepts a `task<T>` for immediate execution.
1026
1027		@see @ref task
1028		@see @ref Executor
1029		@see @ref run_async_wrapper
1030		*/
1031		template<Executor Ex, detail::Allocator Alloc>
1032		[[nodiscard]] auto
1033	319x	run_async(Ex ex, Alloc alloc)
1034		{
1035		return run_async_wrapper<Ex, detail::default_handler, Alloc>(
1036	319x	std::move(ex),
1037	637x	std::stop_token{},
1038		detail::default_handler{},
1039	955x	std::move(alloc));
1040		}
1041
1042		/** Bind an executor, an allocator, and a result handler to produce a launcher. Invoke the launcher with a task to start it.
1043
1044		Construct the task as the direct argument of the two-call expression
1045		`run_async(ex)(task)`.
1046
1047		@par Thread Safety
1048		The wrapper itself should only be used from one thread. The handlers
1049		may be invoked from any thread where the executor schedules work.
1050
1051		@param ex The executor to execute the task on.
1052		@param alloc The allocator for frame allocation (copied and stored).
1053		@param h1 The handler to invoke with the result (and optionally exception).
1054
1055		@return A wrapper that accepts a `task<T>` for immediate execution.
1056
1057		@see @ref task
1058		@see @ref Executor
1059		@see @ref run_async_wrapper
1060		*/
1061		template<Executor Ex, detail::Allocator Alloc, class H1>
1062		[[nodiscard]] auto
1063	3x	run_async(Ex ex, Alloc alloc, H1 h1)
1064		{
1065		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, Alloc>(
1066	3x	std::move(ex),
1067	3x	std::stop_token{},
1068	3x	detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
1069	11x	std::move(alloc));
1070		}
1071
1072		/** Bind an executor, an allocator, and separate result and error handlers to produce a launcher. Invoke the launcher with a task to start it.
1073
1074		Construct the task as the direct argument of the two-call expression
1075		`run_async(ex)(task)`.
1076
1077		@par Thread Safety
1078		The wrapper itself should only be used from one thread. The handlers
1079		may be invoked from any thread where the executor schedules work.
1080
1081		@param ex The executor to execute the task on.
1082		@param alloc The allocator for frame allocation (copied and stored).
1083		@param h1 The handler to invoke with the result on success.
1084		@param h2 The handler to invoke with the exception on failure.
1085
1086		@return A wrapper that accepts a `task<T>` for immediate execution.
1087
1088		@see @ref task
1089		@see @ref Executor
1090		@see @ref run_async_wrapper
1091		*/
1092		template<Executor Ex, detail::Allocator Alloc, class H1, class H2>
1093		[[nodiscard]] auto
1094	4x	run_async(Ex ex, Alloc alloc, H1 h1, H2 h2)
1095		{
1096		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, Alloc>(
1097	4x	std::move(ex),
1098	4x	std::stop_token{},
1099	4x	detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
1100	13x	std::move(alloc));
1101	3x	}
1102
1103		// Ex + stop_token + standard Allocator
1104
1105		/** Bind an executor, a stop token, and an allocator to produce a launcher. Invoke the launcher with a task to start it.
1106
1107		Construct the task as the direct argument of the two-call expression
1108		`run_async(ex)(task)`.
1109
1110		@par Thread Safety
1111		The wrapper itself should only be used from one thread.
1112
1113		@param ex The executor to execute the task on.
1114		@param st The stop token for cooperative cancellation.
1115		@param alloc The allocator for frame allocation (copied and stored).
1116
1117		@return A wrapper that accepts a `task<T>` for immediate execution.
1118
1119		@see @ref task
1120		@see @ref Executor
1121		@see @ref run_async_wrapper
1122		*/
1123		template<Executor Ex, detail::Allocator Alloc>
1124		[[nodiscard]] auto
1125	2001x	run_async(Ex ex, std::stop_token st, Alloc alloc)
1126		{
1127		return run_async_wrapper<Ex, detail::default_handler, Alloc>(
1128	2001x	std::move(ex),
1129	2001x	std::move(st),
1130		detail::default_handler{},
1131	6003x	std::move(alloc));
1132		}
1133
1134		/** Bind an executor, a stop token, an allocator, and a result handler to produce a launcher. Invoke the launcher with a task to start it.
1135
1136		Construct the task as the direct argument of the two-call expression
1137		`run_async(ex)(task)`.
1138
1139		@par Thread Safety
1140		The wrapper itself should only be used from one thread. The handlers
1141		may be invoked from any thread where the executor schedules work.
1142
1143		@param ex The executor to execute the task on.
1144		@param st The stop token for cooperative cancellation.
1145		@param alloc The allocator for frame allocation (copied and stored).
1146		@param h1 The handler to invoke with the result (and optionally exception).
1147
1148		@return A wrapper that accepts a `task<T>` for immediate execution.
1149
1150		@see @ref task
1151		@see @ref Executor
1152		@see @ref run_async_wrapper
1153		*/
1154		template<Executor Ex, detail::Allocator Alloc, class H1>
1155		[[nodiscard]] auto
1156		run_async(Ex ex, std::stop_token st, Alloc alloc, H1 h1)
1157		{
1158		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, Alloc>(
1159		std::move(ex),
1160		std::move(st),
1161		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
1162		std::move(alloc));
1163		}
1164
1165		/** Bind an executor, a stop token, an allocator, and separate result and error handlers to produce a launcher. Invoke the launcher with a task to start it.
1166
1167		Construct the task as the direct argument of the two-call expression
1168		`run_async(ex)(task)`.
1169
1170		@par Thread Safety
1171		The wrapper itself should only be used from one thread. The handlers
1172		may be invoked from any thread where the executor schedules work.
1173
1174		@param ex The executor to execute the task on.
1175		@param st The stop token for cooperative cancellation.
1176		@param alloc The allocator for frame allocation (copied and stored).
1177		@param h1 The handler to invoke with the result on success.
1178		@param h2 The handler to invoke with the exception on failure.
1179
1180		@return A wrapper that accepts a `task<T>` for immediate execution.
1181
1182		@see @ref task
1183		@see @ref Executor
1184		@see @ref run_async_wrapper
1185		*/
1186		template<Executor Ex, detail::Allocator Alloc, class H1, class H2>
1187		[[nodiscard]] auto
1188		run_async(Ex ex, std::stop_token st, Alloc alloc, H1 h1, H2 h2)
1189		{
1190		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, Alloc>(
1191		std::move(ex),
1192		std::move(st),
1193		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
1194		std::move(alloc));
1195		}
1196
1197		} // namespace capy
1198		} // namespace boost
1199
1200		#endif
1201