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	3135x	bool await_ready() const noexcept { return false; }
58
59	3135x	bool await_suspend(std::coroutine_handle<Promise> h) noexcept
60		{
61	3135x	p_ = &h.promise();
62	3135x	return false;
63		}
64
65	3135x	Promise& await_resume() const noexcept
66		{
67	3135x	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	3135x	std::suspend_never final_suspend() noexcept
257		{
258	3135x	return {};
259		}
260
261	3130x	void return_void() noexcept
262		{
263	3130x	}
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	3135x	static void invoke_impl(void* p, Handlers& h)
274		{
275		using R = decltype(std::declval<Task&>().await_resume());
276	3135x	auto& promise = static_cast<typename Task::promise_type>(p);
277	3135x	if(promise.exception())
278	1051x	h(promise.exception());
279		else if constexpr(std::is_void_v<R>)
280	1932x	h();
281		else
282	152x	h(std::move(promise.result()));
283	3130x	}
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	3272x	p.task_cont_.h = task_h;
416	3272x	p.wg_.executor().dispatch(p.task_cont_).resume();
417	6544x	}
418		};
419
420		// Executor only (uses default recycling allocator)
421
422		/** Asynchronously launch a lazy task on the given executor.
423
424		Use this to start execution of a `task<T>` that was created lazily.
425		The returned wrapper must be immediately invoked with the task;
426		storing the wrapper and calling it later violates LIFO ordering.
427
428		Uses the default recycling frame allocator for coroutine frames.
429		With no handlers, the result is discarded and exceptions are rethrown.
430
431		@par Thread Safety
432		The wrapper and handlers may be called from any thread where the
433		executor schedules work.
434
435		@par Example
436		@code
437		run_async(ioc.get_executor())(my_task());
438		@endcode
439
440		@param ex The executor to execute the task on.
441
442		@return A wrapper that accepts a `task<T>` for immediate execution.
443
444		@see task
445		@see executor
446		*/
447		template<Executor Ex>
448		[[nodiscard]] auto
449	2x	run_async(Ex ex)
450		{
451	2x	auto* mr = ex.context().get_frame_allocator();
452		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
453	2x	std::move(ex),
454	4x	std::stop_token{},
455		detail::default_handler{},
456	2x	mr);
457		}
458
459		/** Asynchronously launch a lazy task with a result handler.
460
461		The handler `h1` is called with the task's result on success. If `h1`
462		is also invocable with `std::exception_ptr`, it handles exceptions too.
463		Otherwise, exceptions are rethrown.
464
465		@par Thread Safety
466		The handler may be called from any thread where the executor
467		schedules work.
468
469		@par Example
470		@code
471		// Handler for result only (exceptions rethrown)
472		run_async(ex, [](int result) {
473		std::cout << "Got: " << result << "\n";
474		})(compute_value());
475
476		// Overloaded handler for both result and exception
477		run_async(ex, overloaded{
478		[](int result) { std::cout << "Got: " << result << "\n"; },
479		[](std::exception_ptr) { std::cout << "Failed\n"; }
480		})(compute_value());
481		@endcode
482
483		@param ex The executor to execute the task on.
484		@param h1 The handler to invoke with the result (and optionally exception).
485
486		@return A wrapper that accepts a `task<T>` for immediate execution.
487
488		@see task
489		@see executor
490		*/
491		template<Executor Ex, class H1>
492		[[nodiscard]] auto
493	89x	run_async(Ex ex, H1 h1)
494		{
495	89x	auto* mr = ex.context().get_frame_allocator();
496		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
497	89x	std::move(ex),
498	89x	std::stop_token{},
499	89x	detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
500	178x	mr);
501		}
502
503		/** Asynchronously launch a lazy task with separate result and error handlers.
504
505		The handler `h1` is called with the task's result on success.
506		The handler `h2` is called with the exception_ptr on failure.
507
508		@par Thread Safety
509		The handlers may be called from any thread where the executor
510		schedules work.
511
512		@par Example
513		@code
514		run_async(ex,
515		[](int result) { std::cout << "Got: " << result << "\n"; },
516		[](std::exception_ptr ep) {
517		try { std::rethrow_exception(ep); }
518		catch (std::exception const& e) {
519		std::cout << "Error: " << e.what() << "\n";
520		}
521		}
522		)(compute_value());
523		@endcode
524
525		@param ex The executor to execute the task on.
526		@param h1 The handler to invoke with the result on success.
527		@param h2 The handler to invoke with the exception on failure.
528
529		@return A wrapper that accepts a `task<T>` for immediate execution.
530
531		@see task
532		@see executor
533		*/
534		template<Executor Ex, class H1, class H2>
535		[[nodiscard]] auto
536	111x	run_async(Ex ex, H1 h1, H2 h2)
537		{
538	111x	auto* mr = ex.context().get_frame_allocator();
539		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
540	111x	std::move(ex),
541	111x	std::stop_token{},
542	111x	detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
543	222x	mr);
544	1x	}
545
546		// Ex + stop_token
547
548		/** Asynchronously launch a lazy task with stop token support.
549
550		The stop token is propagated to the task, enabling cooperative
551		cancellation. With no handlers, the result is discarded and
552		exceptions are rethrown.
553
554		@par Thread Safety
555		The wrapper may be called from any thread where the executor
556		schedules work.
557
558		@par Example
559		@code
560		std::stop_source source;
561		run_async(ex, source.get_token())(cancellable_task());
562		// Later: source.request_stop();
563		@endcode
564
565		@param ex The executor to execute the task on.
566		@param st The stop token for cooperative cancellation.
567
568		@return A wrapper that accepts a `task<T>` for immediate execution.
569
570		@see task
571		@see executor
572		*/
573		template<Executor Ex>
574		[[nodiscard]] auto
575	260x	run_async(Ex ex, std::stop_token st)
576		{
577	260x	auto* mr = ex.context().get_frame_allocator();
578		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
579	260x	std::move(ex),
580	260x	std::move(st),
581		detail::default_handler{},
582	520x	mr);
583		}
584
585		/** Asynchronously launch a lazy task with stop token and result handler.
586
587		The stop token is propagated to the task for cooperative cancellation.
588		The handler `h1` is called with the result on success, and optionally
589		with exception_ptr if it accepts that type.
590
591		@param ex The executor to execute the task on.
592		@param st The stop token for cooperative cancellation.
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		*/
600		template<Executor Ex, class H1>
601		[[nodiscard]] auto
602	2801x	run_async(Ex ex, std::stop_token st, H1 h1)
603		{
604	2801x	auto* mr = ex.context().get_frame_allocator();
605		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
606	2801x	std::move(ex),
607	2801x	std::move(st),
608	2801x	detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
609	5602x	mr);
610		}
611
612		/** Asynchronously launch a lazy task with stop token and separate handlers.
613
614		The stop token is propagated to the task for cooperative cancellation.
615		The handler `h1` is called on success, `h2` on failure.
616
617		@param ex The executor to execute the task on.
618		@param st The stop token for cooperative cancellation.
619		@param h1 The handler to invoke with the result on success.
620		@param h2 The handler to invoke with the exception on failure.
621
622		@return A wrapper that accepts a `task<T>` for immediate execution.
623
624		@see task
625		@see executor
626		*/
627		template<Executor Ex, class H1, class H2>
628		[[nodiscard]] auto
629	9x	run_async(Ex ex, std::stop_token st, H1 h1, H2 h2)
630		{
631	9x	auto* mr = ex.context().get_frame_allocator();
632		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
633	9x	std::move(ex),
634	9x	std::move(st),
635	9x	detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
636	18x	mr);
637		}
638
639		// Ex + memory_resource*
640
641		/** Asynchronously launch a lazy task with custom memory resource.
642
643		The memory resource is used for coroutine frame allocation. The caller
644		is responsible for ensuring the memory resource outlives all tasks.
645
646		@param ex The executor to execute the task on.
647		@param mr The memory resource for frame allocation.
648
649		@return A wrapper that accepts a `task<T>` for immediate execution.
650
651		@see task
652		@see executor
653		*/
654		template<Executor Ex>
655		[[nodiscard]] auto
656		run_async(Ex ex, std::pmr::memory_resource* mr)
657		{
658		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
659		std::move(ex),
660		std::stop_token{},
661		detail::default_handler{},
662		mr);
663		}
664
665		/** Asynchronously launch a lazy task with memory resource and handler.
666
667		@param ex The executor to execute the task on.
668		@param mr The memory resource for frame allocation.
669		@param h1 The handler to invoke with the result (and optionally exception).
670
671		@return A wrapper that accepts a `task<T>` for immediate execution.
672
673		@see task
674		@see executor
675		*/
676		template<Executor Ex, class H1>
677		[[nodiscard]] auto
678		run_async(Ex ex, std::pmr::memory_resource* mr, H1 h1)
679		{
680		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
681		std::move(ex),
682		std::stop_token{},
683		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
684		mr);
685		}
686
687		/** Asynchronously launch a lazy task with memory resource and handlers.
688
689		@param ex The executor to execute the task on.
690		@param mr The memory resource for frame allocation.
691		@param h1 The handler to invoke with the result on success.
692		@param h2 The handler to invoke with the exception on failure.
693
694		@return A wrapper that accepts a `task<T>` for immediate execution.
695
696		@see task
697		@see executor
698		*/
699		template<Executor Ex, class H1, class H2>
700		[[nodiscard]] auto
701		run_async(Ex ex, std::pmr::memory_resource* mr, H1 h1, H2 h2)
702		{
703		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
704		std::move(ex),
705		std::stop_token{},
706		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
707		mr);
708		}
709
710		// Ex + stop_token + memory_resource*
711
712		/** Asynchronously launch a lazy task with stop token and memory resource.
713
714		@param ex The executor to execute the task on.
715		@param st The stop token for cooperative cancellation.
716		@param mr The memory resource for frame allocation.
717
718		@return A wrapper that accepts a `task<T>` for immediate execution.
719
720		@see task
721		@see executor
722		*/
723		template<Executor Ex>
724		[[nodiscard]] auto
725		run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr)
726		{
727		return run_async_wrapper<Ex, detail::default_handler, std::pmr::memory_resource*>(
728		std::move(ex),
729		std::move(st),
730		detail::default_handler{},
731		mr);
732		}
733
734		/** Asynchronously launch a lazy task with stop token, memory resource, and handler.
735
736		@param ex The executor to execute the task on.
737		@param st The stop token for cooperative cancellation.
738		@param mr The memory resource for frame allocation.
739		@param h1 The handler to invoke with the result (and optionally exception).
740
741		@return A wrapper that accepts a `task<T>` for immediate execution.
742
743		@see task
744		@see executor
745		*/
746		template<Executor Ex, class H1>
747		[[nodiscard]] auto
748		run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr, H1 h1)
749		{
750		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, std::pmr::memory_resource*>(
751		std::move(ex),
752		std::move(st),
753		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
754		mr);
755		}
756
757		/** Asynchronously launch a lazy task with stop token, memory resource, and handlers.
758
759		@param ex The executor to execute the task on.
760		@param st The stop token for cooperative cancellation.
761		@param mr The memory resource for frame allocation.
762		@param h1 The handler to invoke with the result on success.
763		@param h2 The handler to invoke with the exception on failure.
764
765		@return A wrapper that accepts a `task<T>` for immediate execution.
766
767		@see task
768		@see executor
769		*/
770		template<Executor Ex, class H1, class H2>
771		[[nodiscard]] auto
772		run_async(Ex ex, std::stop_token st, std::pmr::memory_resource* mr, H1 h1, H2 h2)
773		{
774		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, std::pmr::memory_resource*>(
775		std::move(ex),
776		std::move(st),
777		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
778		mr);
779		}
780
781		// Ex + standard Allocator (value type)
782
783		/** Asynchronously launch a lazy task with custom allocator.
784
785		The allocator is wrapped in a frame_memory_resource and stored in the
786		run_async_trampoline, ensuring it outlives all coroutine frames.
787
788		@param ex The executor to execute the task on.
789		@param alloc The allocator for frame allocation (copied and stored).
790
791		@return A wrapper that accepts a `task<T>` for immediate execution.
792
793		@see task
794		@see executor
795		*/
796		template<Executor Ex, detail::Allocator Alloc>
797		[[nodiscard]] auto
798		run_async(Ex ex, Alloc alloc)
799		{
800		return run_async_wrapper<Ex, detail::default_handler, Alloc>(
801		std::move(ex),
802		std::stop_token{},
803		detail::default_handler{},
804		std::move(alloc));
805		}
806
807		/** Asynchronously launch a lazy task with allocator and handler.
808
809		@param ex The executor to execute the task on.
810		@param alloc The allocator for frame allocation (copied and stored).
811		@param h1 The handler to invoke with the result (and optionally exception).
812
813		@return A wrapper that accepts a `task<T>` for immediate execution.
814
815		@see task
816		@see executor
817		*/
818		template<Executor Ex, detail::Allocator Alloc, class H1>
819		[[nodiscard]] auto
820		run_async(Ex ex, Alloc alloc, H1 h1)
821		{
822		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, Alloc>(
823		std::move(ex),
824		std::stop_token{},
825		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
826		std::move(alloc));
827		}
828
829		/** Asynchronously launch a lazy task with allocator and handlers.
830
831		@param ex The executor to execute the task on.
832		@param alloc The allocator for frame allocation (copied and stored).
833		@param h1 The handler to invoke with the result on success.
834		@param h2 The handler to invoke with the exception on failure.
835
836		@return A wrapper that accepts a `task<T>` for immediate execution.
837
838		@see task
839		@see executor
840		*/
841		template<Executor Ex, detail::Allocator Alloc, class H1, class H2>
842		[[nodiscard]] auto
843		run_async(Ex ex, Alloc alloc, H1 h1, H2 h2)
844		{
845		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, Alloc>(
846		std::move(ex),
847		std::stop_token{},
848		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
849		std::move(alloc));
850		}
851
852		// Ex + stop_token + standard Allocator
853
854		/** Asynchronously launch a lazy task with stop token and allocator.
855
856		@param ex The executor to execute the task on.
857		@param st The stop token for cooperative cancellation.
858		@param alloc The allocator for frame allocation (copied and stored).
859
860		@return A wrapper that accepts a `task<T>` for immediate execution.
861
862		@see task
863		@see executor
864		*/
865		template<Executor Ex, detail::Allocator Alloc>
866		[[nodiscard]] auto
867		run_async(Ex ex, std::stop_token st, Alloc alloc)
868		{
869		return run_async_wrapper<Ex, detail::default_handler, Alloc>(
870		std::move(ex),
871		std::move(st),
872		detail::default_handler{},
873		std::move(alloc));
874		}
875
876		/** Asynchronously launch a lazy task with stop token, allocator, and handler.
877
878		@param ex The executor to execute the task on.
879		@param st The stop token for cooperative cancellation.
880		@param alloc The allocator for frame allocation (copied and stored).
881		@param h1 The handler to invoke with the result (and optionally exception).
882
883		@return A wrapper that accepts a `task<T>` for immediate execution.
884
885		@see task
886		@see executor
887		*/
888		template<Executor Ex, detail::Allocator Alloc, class H1>
889		[[nodiscard]] auto
890		run_async(Ex ex, std::stop_token st, Alloc alloc, H1 h1)
891		{
892		return run_async_wrapper<Ex, detail::handler_pair<H1, detail::default_handler>, Alloc>(
893		std::move(ex),
894		std::move(st),
895		detail::handler_pair<H1, detail::default_handler>{std::move(h1)},
896		std::move(alloc));
897		}
898
899		/** Asynchronously launch a lazy task with stop token, allocator, and handlers.
900
901		@param ex The executor to execute the task on.
902		@param st The stop token for cooperative cancellation.
903		@param alloc The allocator for frame allocation (copied and stored).
904		@param h1 The handler to invoke with the result on success.
905		@param h2 The handler to invoke with the exception on failure.
906
907		@return A wrapper that accepts a `task<T>` for immediate execution.
908
909		@see task
910		@see executor
911		*/
912		template<Executor Ex, detail::Allocator Alloc, class H1, class H2>
913		[[nodiscard]] auto
914		run_async(Ex ex, std::stop_token st, Alloc alloc, H1 h1, H2 h2)
915		{
916		return run_async_wrapper<Ex, detail::handler_pair<H1, H2>, Alloc>(
917		std::move(ex),
918		std::move(st),
919		detail::handler_pair<H1, H2>{std::move(h1), std::move(h2)},
920		std::move(alloc));
921		}
922
923		} // namespace capy
924		} // namespace boost
925
926		#endif
927