include/boost/capy/ex/run_async.hpp

94.8% Lines (13258/13992) 93.1% List of functions (3353/3602)

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

run_async.hpp

f(x) Functions (3602)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3		//
4		// Distributed under the Boost Software License, Version 1.0. (See accompanying
5		// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6		//
7		// Official repository: https://github.com/cppalliance/capy
8		//
9
10		#ifndef BOOST_CAPY_RUN_ASYNC_HPP
11		#define BOOST_CAPY_RUN_ASYNC_HPP
12
13		#include <boost/capy/detail/config.hpp>
14		#include <boost/capy/detail/run.hpp>
15		#include <boost/capy/detail/run_callbacks.hpp>
16		#include <boost/capy/concept/executor.hpp>
17		#include <boost/capy/concept/io_runnable.hpp>
18		#include <boost/capy/ex/execution_context.hpp>
19		#include <boost/capy/ex/frame_allocator.hpp>
20		#include <boost/capy/ex/io_env.hpp>
21		#include <boost/capy/ex/recycling_memory_resource.hpp>
22		#include <boost/capy/ex/work_guard.hpp>
23
24		#include <algorithm>
25		#include <coroutine>
26		#include <cstring>
27		#include <memory_resource>
28		#include <new>
29		#include <stop_token>
30		#include <type_traits>
31
32		namespace boost {
33		namespace capy {
34		namespace detail {
35
36		/// Function pointer type for type-erased frame deallocation.
37		using dealloc_fn = void()(void, std::size_t);
38
39		/// Type-erased deallocator implementation for trampoline frames.
40		template<class Alloc>
41		void dealloc_impl(void* raw, std::size_t total)
42		{
43		static_assert(std::is_same_v<typename Alloc::value_type, std::byte>);
44		auto* a = std::launder(reinterpret_cast<Alloc*>(
45		static_cast<char*>(raw) + total - sizeof(Alloc)));
46		Alloc ba(std::move(*a));
47		a->~Alloc();
48		ba.deallocate(static_cast<std::byte*>(raw), total);
49		}
50
51		/// Awaiter to access the promise from within the coroutine.
52		template<class Promise>
53		struct get_promise_awaiter
54		{
55		Promise* p_ = nullptr;
56
57	3124x	bool await_ready() const noexcept { return false; }
58
59	3124x	bool await_suspend(std::coroutine_handle<Promise> h) noexcept
60		{
61	3124x	p_ = &h.promise();
62	3124x	return false;
63		}
64
65	3124x	Promise& await_resume() const noexcept
66		{
67	3124x	return *p_;
68		}
69		};
70
71		/** Internal run_async_trampoline coroutine for run_async.
72
73		The run_async_trampoline is allocated BEFORE the task (via C++17 postfix evaluation
74		order) and serves as the task's continuation. When the task final_suspends,
75		control returns to the run_async_trampoline which then invokes the appropriate handler.
76
77		For value-type allocators, the run_async_trampoline stores a frame_memory_resource
78		that wraps the allocator. For memory_resource*, it stores the pointer directly.
79
80		@tparam Ex The executor type.
81		@tparam Handlers The handler type (default_handler or handler_pair).
82		@tparam Alloc The allocator type (value type or memory_resource*).
83		*/
84		template<class Ex, class Handlers, class Alloc>
85		struct run_async_trampoline
86		{
87		using invoke_fn = void()(void, Handlers&);
88
89		struct promise_type
90		{
91		work_guard<Ex> wg_;
92		Handlers handlers_;
93		frame_memory_resource<Alloc> resource_;
94		io_env env_;
95		invoke_fn invoke_ = nullptr;
96		void* task_promise_ = nullptr;
97		// task_h_: raw handle for frame_guard cleanup in make_trampoline.
98		// task_cont_: continuation wrapping the same handle for executor dispatch.
99		// Both must reference the same coroutine and be kept in sync.
100		std::coroutine_handle<> task_h_;
101		continuation task_cont_;
102
103		promise_type(Ex& ex, Handlers& h, Alloc& a) noexcept
104		: wg_(std::move(ex))
105		, handlers_(std::move(h))
106		, resource_(std::move(a))
107		{
108		}
109
110		static void* operator new(
111		std::size_t size, Ex const&, Handlers const&, Alloc a)
112		{
113		using byte_alloc = typename std::allocator_traits<Alloc>
114		::template rebind_alloc<std::byte>;
115
116		constexpr auto footer_align =
117		(std::max)(alignof(dealloc_fn), alignof(Alloc));
118		auto padded = (size + footer_align - 1) & ~(footer_align - 1);
119		auto total = padded + sizeof(dealloc_fn) + sizeof(Alloc);
120
121		byte_alloc ba(std::move(a));
122		void* raw = ba.allocate(total);
123
124		auto* fn_loc = reinterpret_cast<dealloc_fn*>(
125		static_cast<char*>(raw) + padded);
126		*fn_loc = &dealloc_impl<byte_alloc>;
127
128		new (fn_loc + 1) byte_alloc(std::move(ba));
129
130		return raw;
131		}
132
133	✗	static void operator delete(void* ptr, std::size_t size)
134		{
135	✗	constexpr auto footer_align =
136		(std::max)(alignof(dealloc_fn), alignof(Alloc));
137	✗	auto padded = (size + footer_align - 1) & ~(footer_align - 1);
138	✗	auto total = padded + sizeof(dealloc_fn) + sizeof(Alloc);
139
140	✗	auto* fn = reinterpret_cast<dealloc_fn*>(
141		static_cast<char*>(ptr) + padded);
142	✗	(*fn)(ptr, total);
143	✗	}
144
145		std::pmr::memory_resource* get_resource() noexcept
146		{
147		return &resource_;
148		}
149
150		run_async_trampoline get_return_object() noexcept
151		{
152		return run_async_trampoline{
153		std::coroutine_handle<promise_type>::from_promise(*this)};
154		}
155
156	✗	std::suspend_always initial_suspend() noexcept
157		{
158	✗	return {};
159		}
160
161	✗	std::suspend_never final_suspend() noexcept
162		{
163	✗	return {};
164		}
165
166	✗	void return_void() noexcept
167		{
168	✗	}
169
170	✗	void unhandled_exception() noexcept
171		{
172	✗	}
173		};
174
175		std::coroutine_handle<promise_type> h_;
176
177		template<IoRunnable Task>
178		static void invoke_impl(void* p, Handlers& h)
179		{
180		using R = decltype(std::declval<Task&>().await_resume());
181		auto& promise = static_cast<typename Task::promise_type>(p);
182		if(promise.exception())
183		h(promise.exception());
184		else if constexpr(std::is_void_v<R>)
185		h();
186		else
187		h(std::move(promise.result()));
188		}
189		};
190
191		/** Specialization for memory_resource* - stores pointer directly.
192
193		This avoids double indirection when the user passes a memory_resource*.
194		*/
195		template<class Ex, class Handlers>
196		struct run_async_trampoline<Ex, Handlers, std::pmr::memory_resource*>
197		{
198		using invoke_fn = void()(void, Handlers&);
199
200		struct promise_type
201		{
202		work_guard<Ex> wg_;
203		Handlers handlers_;
204		std::pmr::memory_resource* mr_;
205		io_env env_;
206		invoke_fn invoke_ = nullptr;
207		void* task_promise_ = nullptr;
208		// task_h_: raw handle for frame_guard cleanup in make_trampoline.
209		// task_cont_: continuation wrapping the same handle for executor dispatch.
210		// Both must reference the same coroutine and be kept in sync.
211		std::coroutine_handle<> task_h_;
212		continuation task_cont_;
213
214	3272x	promise_type(
215		Ex& ex, Handlers& h, std::pmr::memory_resource* mr) noexcept
216	3272x	: wg_(std::move(ex))
217	3272x	, handlers_(std::move(h))
218	3272x	, mr_(mr)
219		{
220	3272x	}
221
222	3272x	static void* operator new(
223		std::size_t size, Ex const&, Handlers const&,
224		std::pmr::memory_resource* mr)
225		{
226	3272x	auto total = size + sizeof(mr);
227	3272x	void* raw = mr->allocate(total, alignof(std::max_align_t));
228	3272x	std::memcpy(static_cast<char*>(raw) + size, &mr, sizeof(mr));
229	3272x	return raw;
230		}
231
232	3272x	static void operator delete(void* ptr, std::size_t size)
233		{
234		std::pmr::memory_resource* mr;
235	3272x	std::memcpy(&mr, static_cast<char*>(ptr) + size, sizeof(mr));
236	3272x	auto total = size + sizeof(mr);
237	3272x	mr->deallocate(ptr, total, alignof(std::max_align_t));
238	3272x	}
239
240	6544x	std::pmr::memory_resource* get_resource() noexcept
241		{
242	6544x	return mr_;
243		}
244
245	3272x	run_async_trampoline get_return_object() noexcept
246		{
247		return run_async_trampoline{
248	3272x	std::coroutine_handle<promise_type>::from_promise(*this)};
249		}
250
251	3272x	std::suspend_always initial_suspend() noexcept
252		{
253	3272x	return {};
254		}
255
256	3124x	std::suspend_never final_suspend() noexcept
257		{
258	3124x	return {};
259		}
260
261	3119x	void return_void() noexcept
262		{
263	3119x	}
264
265	5x	void unhandled_exception() noexcept
266		{
267	5x	}
268		};
269
270		std::coroutine_handle<promise_type> h_;
271
272		template<IoRunnable Task>
273	3124x	static void invoke_impl(void* p, Handlers& h)
274		{
275		using R = decltype(std::declval<Task&>().await_resume());
276	3124x	auto& promise = static_cast<typename Task::promise_type>(p);
277	3124x	if(promise.exception())
278	1051x	h(promise.exception());
279		else if constexpr(std::is_void_v<R>)
280	1921x	h();
281		else
282	152x	h(std::move(promise.result()));
283	3119x	}
284		};
285
286		/// Coroutine body for run_async_trampoline - invokes handlers then destroys task.
287		template<class Ex, class Handlers, class Alloc>
288		run_async_trampoline<Ex, Handlers, Alloc>
289	3272x	make_trampoline(Ex, Handlers, Alloc)
290		{
291		// promise_type ctor steals the parameters
292		auto& p = co_await get_promise_awaiter<
293		typename run_async_trampoline<Ex, Handlers, Alloc>::promise_type>{};
294
295		// Guard ensures the task frame is destroyed even when invoke_
296		// throws (e.g. default_handler rethrows an unhandled exception).
297		struct frame_guard
298		{
299		std::coroutine_handle<>& h;
300	2726x	~frame_guard() { h.destroy(); }
301		} guard{p.task_h_};
302
303		p.invoke_(p.task_promise_, p.handlers_);
304	6544x	}
305
306		} // namespace detail
307
308		/** Wrapper returned by run_async that accepts a task for execution.
309
310		This wrapper holds the run_async_trampoline coroutine, executor, stop token,
311		and handlers. The run_async_trampoline is allocated when the wrapper is constructed
312		(before the task due to C++17 postfix evaluation order).
313
314		The rvalue ref-qualifier on `operator()` ensures the wrapper can only
315		be used as a temporary, preventing misuse that would violate LIFO ordering.
316
317		@tparam Ex The executor type satisfying the `Executor` concept.
318		@tparam Handlers The handler type (default_handler or handler_pair).
319		@tparam Alloc The allocator type (value type or memory_resource*).
320
321		@par Thread Safety
322		The wrapper itself should only be used from one thread. The handlers
323		may be invoked from any thread where the executor schedules work.
324
325		@par Example
326		@code
327		// Correct usage - wrapper is temporary
328		run_async(ex)(my_task());
329
330		// Compile error - cannot call operator() on lvalue
331		auto w = run_async(ex);
332		w(my_task()); // Error: operator() requires rvalue
333		@endcode
334
335		@see run_async
336		*/
337		template<Executor Ex, class Handlers, class Alloc>
338		class [[nodiscard]] run_async_wrapper
339		{
340		detail::run_async_trampoline<Ex, Handlers, Alloc> tr_;
341		std::stop_token st_;
342		std::pmr::memory_resource* saved_tls_;
343
344		public:
345		/// Construct wrapper with executor, stop token, handlers, and allocator.
346	3272x	run_async_wrapper(
347		Ex ex,
348		std::stop_token st,
349		Handlers h,
350		Alloc a) noexcept
351	3273x	: tr_(detail::make_trampoline<Ex, Handlers, Alloc>(
352	3273x	std::move(ex), std::move(h), std::move(a)))
353	3272x	, st_(std::move(st))
354	3272x	, saved_tls_(get_current_frame_allocator())
355		{
356		if constexpr (!std::is_same_v<Alloc, std::pmr::memory_resource*>)
357		{
358		static_assert(
359		std::is_nothrow_move_constructible_v<Alloc>,
360		"Allocator must be nothrow move constructible");
361		}
362		// Set TLS before task argument is evaluated
363	3272x	set_current_frame_allocator(tr_.h_.promise().get_resource());
364	3272x	}
365
366	3272x	~run_async_wrapper()
367		{
368		// Restore TLS so stale pointer doesn't outlive
369		// the execution context that owns the resource.
370	3272x	set_current_frame_allocator(saved_tls_);
371	3272x	}
372
373		// Non-copyable, non-movable (must be used immediately)
374		run_async_wrapper(run_async_wrapper const&) = delete;
375		run_async_wrapper(run_async_wrapper&&) = delete;
376		run_async_wrapper& operator=(run_async_wrapper const&) = delete;
377		run_async_wrapper& operator=(run_async_wrapper&&) = delete;
378
379		/** Launch the task for execution.
380
381		This operator accepts a task and launches it on the executor.
382		The rvalue ref-qualifier ensures the wrapper is consumed, enforcing
383		correct LIFO destruction order.
384
385		The `io_env` constructed for the task is owned by the trampoline
386		coroutine and is guaranteed to outlive the task and all awaitables
387		in its chain. Awaitables may store `io_env const*` without concern
388		for dangling references.
389
390		@tparam Task The IoRunnable type.
391
392		@param t The task to execute. Ownership is transferred to the
393		run_async_trampoline which will destroy it after completion.
394		*/
395		template<IoRunnable Task>
396	3272x	void operator()(Task t) &&
397		{
398	3272x	auto task_h = t.handle();
399	3272x	auto& task_promise = task_h.promise();
400	3272x	t.release();
401
402	3272x	auto& p = tr_.h_.promise();
403
404		// Inject Task-specific invoke function
405	3272x	p.invoke_ = detail::run_async_trampoline<Ex, Handlers, Alloc>::template invoke_impl<Task>;
406	3272x	p.task_promise_ = &task_promise;
407	3272x	p.task_h_ = task_h;
408
409		// Setup task's continuation to return to run_async_trampoline
410	3272x	task_promise.set_continuation(tr_.h_);
411	6544x	p.env_ = {p.wg_.executor(), st_, p.get_resource()};
412	3272x	task_promise.set_environment(&p.env_);
413
414		// Start task through executor.
415		// safe_resume is not needed here: TLS is already saved in the
416		// constructor (saved_tls_) and restored in the destructor.
417	3272x	p.task_cont_.h = task_h;
418	3272x	p.wg_.executor().dispatch(p.task_cont_).resume();
419	6544x	}
420		};
421
422		// Executor only (uses default recycling allocator)
423
424		/** Asynchronously launch a lazy task on the given executor.
425
426		Use this to start execution of a `task<T>` that was created lazily.
427		The returned wrapper must be immediately invoked with the task;
428		storing the wrapper and calling it later violates LIFO ordering.
429
430		Uses the default recycling frame allocator for coroutine frames.
431		With no handlers, the result is discarded and exceptions are rethrown.
432
433		@par Thread Safety
434		The wrapper and handlers may be called from any thread where the
435		executor schedules work.
436
437		@par Example
438		@code
439		run_async(ioc.get_executor())(my_task());
440		@endcode
441
442		@param ex The executor to execute the task on.
443
444		@return A wrapper that accepts a `task<T>` for immediate execution.
445
446		@see task
447		@see executor
448		*/
449		template<Executor Ex>
450		[[nodiscard]] auto
451	2x	run_async(Ex ex)
452		{
453	2x	auto* mr = ex.context().get_frame_allocator();
454		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
455	2x	std::move(ex),
456	4x	std::stop_token{},
457		detail::default_handler{},
458	2x	mr);
459		}
460
461		/** Asynchronously launch a lazy task with a result handler.
462
463		The handler `h1` is called with the task's result on success. If `h1`
464		is also invocable with `std::exception_ptr`, it handles exceptions too.
465		Otherwise, exceptions are rethrown.
466
467		@par Thread Safety
468		The handler may be called from any thread where the executor
469		schedules work.
470
471		@par Example
472		@code
473		// Handler for result only (exceptions rethrown)
474		run_async(ex, [](int result) {
475		std::cout << "Got: " << result << "\n";
476		})(compute_value());
477
478		// Overloaded handler for both result and exception
479		run_async(ex, overloaded{
480		[](int result) { std::cout << "Got: " << result << "\n"; },
481		[](std::exception_ptr) { std::cout << "Failed\n"; }
482		})(compute_value());
483		@endcode
484
485		@param ex The executor to execute the task on.
486		@param h1 The handler to invoke with the result (and optionally exception).
487
488		@return A wrapper that accepts a `task<T>` for immediate execution.
489
490		@see task
491		@see executor
492		*/
493		template<Executor Ex, class H1>
494		[[nodiscard]] auto
495	89x	run_async(Ex ex, H1 h1)
496		{
497	89x	auto* mr = ex.context().get_frame_allocator();
498		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
499	89x	std::move(ex),
500	89x	std::stop_token{},
501	89x	detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
502	178x	mr);
503		}
504
505		/** Asynchronously launch a lazy task with separate result and error handlers.
506
507		The handler `h1` is called with the task's result on success.
508		The handler `h2` is called with the exception_ptr on failure.
509
510		@par Thread Safety
511		The handlers may be called from any thread where the executor
512		schedules work.
513
514		@par Example
515		@code
516		run_async(ex,
517		[](int result) { std::cout << "Got: " << result << "\n"; },
518		[](std::exception_ptr ep) {
519		try { std::rethrow_exception(ep); }
520		catch (std::exception const& e) {
521		std::cout << "Error: " << e.what() << "\n";
522		}
523		}
524		)(compute_value());
525		@endcode
526
527		@param ex The executor to execute the task on.
528		@param h1 The handler to invoke with the result on success.
529		@param h2 The handler to invoke with the exception on failure.
530
531		@return A wrapper that accepts a `task<T>` for immediate execution.
532
533		@see task
534		@see executor
535		*/
536		template<Executor Ex, class H1, class H2>
537		[[nodiscard]] auto
538	111x	run_async(Ex ex, H1 h1, H2 h2)
539		{
540	111x	auto* mr = ex.context().get_frame_allocator();
541		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
542	111x	std::move(ex),
543	111x	std::stop_token{},
544	111x	detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
545	222x	mr);
546	1x	}
547
548		// Ex + stop_token
549
550		/** Asynchronously launch a lazy task with stop token support.
551
552		The stop token is propagated to the task, enabling cooperative
553		cancellation. With no handlers, the result is discarded and
554		exceptions are rethrown.
555
556		@par Thread Safety
557		The wrapper may be called from any thread where the executor
558		schedules work.
559
560		@par Example
561		@code
562		std::stop_source source;
563		run_async(ex, source.get_token())(cancellable_task());
564		// Later: source.request_stop();
565		@endcode
566
567		@param ex The executor to execute the task on.
568		@param st The stop token for cooperative cancellation.
569
570		@return A wrapper that accepts a `task<T>` for immediate execution.
571
572		@see task
573		@see executor
574		*/
575		template<Executor Ex>
576		[[nodiscard]] auto
577	260x	run_async(Ex ex, std::stop_token st)
578		{
579	260x	auto* mr = ex.context().get_frame_allocator();
580		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
581	260x	std::move(ex),
582	260x	std::move(st),
583		detail::default_handler{},
584	520x	mr);
585		}
586
587		/** Asynchronously launch a lazy task with stop token and result handler.
588
589		The stop token is propagated to the task for cooperative cancellation.
590		The handler `h1` is called with the result on success, and optionally
591		with exception_ptr if it accepts that type.
592
593		@param ex The executor to execute the task on.
594		@param st The stop token for cooperative cancellation.
595		@param h1 The handler to invoke with the result (and optionally exception).
596
597		@return A wrapper that accepts a `task<T>` for immediate execution.
598
599		@see task
600		@see executor
601		*/
602		template<Executor Ex, class H1>
603		[[nodiscard]] auto
604	2801x	run_async(Ex ex, std::stop_token st, H1 h1)
605		{
606	2801x	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	2801x	std::move(ex),
609	2801x	std::move(st),
610	2801x	detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
611	5602x	mr);
612		}
613
614		/** Asynchronously launch a lazy task with stop token and separate handlers.
615
616		The stop token is propagated to the task for cooperative cancellation.
617		The handler `h1` is called on success, `h2` on failure.
618
619		@param ex The executor to execute the task on.
620		@param st The stop token for cooperative cancellation.
621		@param h1 The handler to invoke with the result on success.
622		@param h2 The handler to invoke with the exception on failure.
623
624		@return A wrapper that accepts a `task<T>` for immediate execution.
625
626		@see task
627		@see executor
628		*/
629		template<Executor Ex, class H1, class H2>
630		[[nodiscard]] auto
631	9x	run_async(Ex ex, std::stop_token st, H1 h1, H2 h2)
632		{
633	9x	auto* mr = ex.context().get_frame_allocator();
634		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
635	9x	std::move(ex),
636	9x	std::move(st),
637	9x	detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
638	18x	mr);
639		}
640
641		// Ex + memory_resource*
642
643		/** Asynchronously launch a lazy task with custom memory resource.
644
645		The memory resource is used for coroutine frame allocation. The caller
646		is responsible for ensuring the memory resource outlives all tasks.
647
648		@param ex The executor to execute the task on.
649		@param mr The memory resource for frame allocation.
650
651		@return A wrapper that accepts a `task<T>` for immediate execution.
652
653		@see task
654		@see executor
655		*/
656		template<Executor Ex>
657		[[nodiscard]] auto
658		run_async(Ex ex, std::pmr::memory_resource* mr)
659		{
660		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
661		std::move(ex),
662		std::stop_token{},
663		detail::default_handler{},
664		mr);
665		}
666
667		/** Asynchronously launch a lazy task with memory resource and handler.
668
669		@param ex The executor to execute the task on.
670		@param mr The memory resource for frame allocation.
671		@param h1 The handler to invoke with the result (and optionally exception).
672
673		@return A wrapper that accepts a `task<T>` for immediate execution.
674
675		@see task
676		@see executor
677		*/
678		template<Executor Ex, class H1>
679		[[nodiscard]] auto
680		run_async(Ex ex, std::pmr::memory_resource* mr, H1 h1)
681		{
682		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
683		std::move(ex),
684		std::stop_token{},
685		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
686		mr);
687		}
688
689		/** Asynchronously launch a lazy task with memory resource and handlers.
690
691		@param ex The executor to execute the task on.
692		@param mr The memory resource for frame allocation.
693		@param h1 The handler to invoke with the result on success.
694		@param h2 The handler to invoke with the exception on failure.
695
696		@return A wrapper that accepts a `task<T>` for immediate execution.
697
698		@see task
699		@see executor
700		*/
701		template<Executor Ex, class H1, class H2>
702		[[nodiscard]] auto
703		run_async(Ex ex, std::pmr::memory_resource* mr, H1 h1, H2 h2)
704		{
705		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
706		std::move(ex),
707		std::stop_token{},
708		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
709		mr);
710		}
711
712		// Ex + stop_token + memory_resource*
713
714		/** Asynchronously launch a lazy task with stop token and memory resource.
715
716		@param ex The executor to execute the task on.
717		@param st The stop token for cooperative cancellation.
718		@param mr The memory resource for frame allocation.
719
720		@return A wrapper that accepts a `task<T>` for immediate execution.
721
722		@see task
723		@see executor
724		*/
725		template<Executor Ex>
726		[[nodiscard]] auto
727		run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr)
728		{
729		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
730		std::move(ex),
731		std::move(st),
732		detail::default_handler{},
733		mr);
734		}
735
736		/** Asynchronously launch a lazy task with stop token, memory resource, and handler.
737
738		@param ex The executor to execute the task on.
739		@param st The stop token for cooperative cancellation.
740		@param mr The memory resource for frame allocation.
741		@param h1 The handler to invoke with the result (and optionally exception).
742
743		@return A wrapper that accepts a `task<T>` for immediate execution.
744
745		@see task
746		@see executor
747		*/
748		template<Executor Ex, class H1>
749		[[nodiscard]] auto
750		run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr, H1 h1)
751		{
752		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
753		std::move(ex),
754		std::move(st),
755		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
756		mr);
757		}
758
759		/** Asynchronously launch a lazy task with stop token, memory resource, and handlers.
760
761		@param ex The executor to execute the task on.
762		@param st The stop token for cooperative cancellation.
763		@param mr The memory resource for frame allocation.
764		@param h1 The handler to invoke with the result on success.
765		@param h2 The handler to invoke with the exception on failure.
766
767		@return A wrapper that accepts a `task<T>` for immediate execution.
768
769		@see task
770		@see executor
771		*/
772		template<Executor Ex, class H1, class H2>
773		[[nodiscard]] auto
774		run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr, H1 h1, H2 h2)
775		{
776		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
777		std::move(ex),
778		std::move(st),
779		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
780		mr);
781		}
782
783		// Ex + standard Allocator (value type)
784
785		/** Asynchronously launch a lazy task with custom allocator.
786
787		The allocator is wrapped in a frame_memory_resource and stored in the
788		run_async_trampoline, ensuring it outlives all coroutine frames.
789
790		@param ex The executor to execute the task on.
791		@param alloc The allocator for frame allocation (copied and stored).
792
793		@return A wrapper that accepts a `task<T>` for immediate execution.
794
795		@see task
796		@see executor
797		*/
798		template<Executor Ex, detail::Allocator Alloc>
799		[[nodiscard]] auto
800		run_async(Ex ex, Alloc alloc)
801		{
802		return run_async_wrapper<Ex, detail::default_handler, Alloc>(
803		std::move(ex),
804		std::stop_token{},
805		detail::default_handler{},
806		std::move(alloc));
807		}
808
809		/** Asynchronously launch a lazy task with allocator and handler.
810
811		@param ex The executor to execute the task on.
812		@param alloc The allocator for frame allocation (copied and stored).
813		@param h1 The handler to invoke with the result (and optionally exception).
814
815		@return A wrapper that accepts a `task<T>` for immediate execution.
816
817		@see task
818		@see executor
819		*/
820		template<Executor Ex, detail::Allocator Alloc, class H1>
821		[[nodiscard]] auto
822		run_async(Ex ex, Alloc alloc, H1 h1)
823		{
824		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, Alloc>(
825		std::move(ex),
826		std::stop_token{},
827		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
828		std::move(alloc));
829		}
830
831		/** Asynchronously launch a lazy task with allocator and handlers.
832
833		@param ex The executor to execute the task on.
834		@param alloc The allocator for frame allocation (copied and stored).
835		@param h1 The handler to invoke with the result on success.
836		@param h2 The handler to invoke with the exception on failure.
837
838		@return A wrapper that accepts a `task<T>` for immediate execution.
839
840		@see task
841		@see executor
842		*/
843		template<Executor Ex, detail::Allocator Alloc, class H1, class H2>
844		[[nodiscard]] auto
845		run_async(Ex ex, Alloc alloc, H1 h1, H2 h2)
846		{
847		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, Alloc>(
848		std::move(ex),
849		std::stop_token{},
850		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
851		std::move(alloc));
852		}
853
854		// Ex + stop_token + standard Allocator
855
856		/** Asynchronously launch a lazy task with stop token and allocator.
857
858		@param ex The executor to execute the task on.
859		@param st The stop token for cooperative cancellation.
860		@param alloc The allocator for frame allocation (copied and stored).
861
862		@return A wrapper that accepts a `task<T>` for immediate execution.
863
864		@see task
865		@see executor
866		*/
867		template<Executor Ex, detail::Allocator Alloc>
868		[[nodiscard]] auto
869		run_async(Ex ex, std::stop_token st, Alloc alloc)
870		{
871		return run_async_wrapper<Ex, detail::default_handler, Alloc>(
872		std::move(ex),
873		std::move(st),
874		detail::default_handler{},
875		std::move(alloc));
876		}
877
878		/** Asynchronously launch a lazy task with stop token, allocator, and handler.
879
880		@param ex The executor to execute the task on.
881		@param st The stop token for cooperative cancellation.
882		@param alloc The allocator for frame allocation (copied and stored).
883		@param h1 The handler to invoke with the result (and optionally exception).
884
885		@return A wrapper that accepts a `task<T>` for immediate execution.
886
887		@see task
888		@see executor
889		*/
890		template<Executor Ex, detail::Allocator Alloc, class H1>
891		[[nodiscard]] auto
892		run_async(Ex ex, std::stop_token st, Alloc alloc, H1 h1)
893		{
894		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, Alloc>(
895		std::move(ex),
896		std::move(st),
897		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
898		std::move(alloc));
899		}
900
901		/** Asynchronously launch a lazy task with stop token, allocator, and handlers.
902
903		@param ex The executor to execute the task on.
904		@param st The stop token for cooperative cancellation.
905		@param alloc The allocator for frame allocation (copied and stored).
906		@param h1 The handler to invoke with the result on success.
907		@param h2 The handler to invoke with the exception on failure.
908
909		@return A wrapper that accepts a `task<T>` for immediate execution.
910
911		@see task
912		@see executor
913		*/
914		template<Executor Ex, detail::Allocator Alloc, class H1, class H2>
915		[[nodiscard]] auto
916		run_async(Ex ex, std::stop_token st, Alloc alloc, H1 h1, H2 h2)
917		{
918		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, Alloc>(
919		std::move(ex),
920		std::move(st),
921		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
922		std::move(alloc));
923		}
924
925		} // namespace capy
926		} // namespace boost
927
928		#endif
929