include/boost/capy/ex/run_async.hpp

100.0% Lines (177/2/179) 98.4% List of functions (4016/246/4327)

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

run_async.hpp

f(x) Functions (4327)

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