include/boost/capy/ex/run_async.hpp

100.0% Lines (152/154) 98.5% List of functions (3793/4083)

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

run_async.hpp

f(x) Functions (4083)

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