include/boost/capy/ex/run_async.hpp

100.0% Lines (154/155) 93.5% List of functions (3794/4065)

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

run_async.hpp

f(x) Functions (4065)

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