include/boost/capy/ex/run_async.hpp

100.0% Lines (162/162) 93.3% List of functions (3826/4101)

[ ] prev/next file

run_async.hpp

f(x) Functions (4101)

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