include/boost/capy/task.hpp

100.0% Lines (95 / 95, 2 excl) 91.9% Functions (1310 / 1425, 2 excl)

[ ] prev/next file

task.hpp

f(x) Functions (1427)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3		// Copyright (c) 2026 Michael Vandeberg
4		//
5		// Distributed under the Boost Software License, Version 1.0. (See accompanying
6		// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7		//
8		// Official repository: https://github.com/cppalliance/capy
9		//
10
11		#ifndef BOOST_CAPY_TASK_HPP
12		#define BOOST_CAPY_TASK_HPP
13
14		#include <boost/capy/detail/config.hpp>
15		#include <boost/capy/concept/executor.hpp>
16		#include <boost/capy/concept/context_awaitable.hpp>
17		#include <boost/capy/ex/context_awaitable_promise_base.hpp>
18		#include <boost/capy/ex/await_context.hpp>
19		#include <boost/capy/ex/frame_allocator.hpp>
20		#include <boost/capy/detail/await_suspend_helper.hpp>
21		#include <boost/capy/results.hpp>
22
23		#include <exception>
24		#include <optional>
25		#include <type_traits>
26		#include <utility>
27		#include <variant>
28
29		namespace boost {
30		namespace capy {
31
32		namespace detail {
33
34		// Helper base for result storage and return_void/return_value
35		template<typename T>
36		struct task_return_base
37		{
38		std::optional<T> result_;
39
40	889x	void return_value(T value)
41		{
42	889x	result_ = std::move(value);
43	889x	}
44
45	279x	T&& result() noexcept
46		{
47	279x	return std::move(*result_);
48		}
49		};
50
51		template<>
52		struct task_return_base<void>
53		{
54	3634x	void return_void()
55		{
56	3634x	}
57		};
58
59		} // namespace detail
60
61		/** Defers a coroutine body until awaited, then runs it inline on the caller's thread.
62
63		Use `task<T>` as the return type for coroutines that perform I/O
64		and return a value of type `T`. The coroutine body does not start
65		executing until the task is awaited, enabling efficient composition
66		without unnecessary eager execution.
67
68		The task participates in the I/O awaitable protocol: when awaited,
69		it receives the caller's executor and stop token, propagating them
70		to nested `co_await` expressions. This enables cancellation and
71		proper completion dispatch across executor boundaries.
72
73		@par Await-effects
74
75		Let `t` be a `task<T>`. `co_await t` always suspends the awaiting
76		coroutine, then transfers control directly into the task's coroutine
77		body on the current thread; no executor operation is posted. The task
78		records the caller's environment (executor, stop token, and frame
79		allocator) by pointer rather than copying it. It propagates that
80		environment to every `co_await` inside the body.
81
82		The body runs until it returns or exits via an exception. Control
83		then transfers directly back to the awaiting coroutine, again
84		without an executor operation.
85
86		`task` never inspects the stop token; it only propagates it. A task
87		body observes a stop request through the results of the operations it
88		awaits, or by reading the token itself. See @ref quitter for a task
89		that stops its own body.
90
91		@par Await-returns
92		The value the body passed to `co_return`, moved out of the task, or
93		nothing when `T` is `void`.
94
95		If the body exits via an unhandled exception, that exception is
96		rethrown instead.
97
98		@par Await-postcondition
99		The task's coroutine has run to completion and is suspended at its
100		final suspend point. The task still owns the frame, but not the
101		result: the await moves it out, so a task must not be awaited twice.
102
103		@par Thread Safety
104		Distinct objects: Safe.
105		Shared objects: Unsafe.
106
107		@par Example
108
109		@par !example example
110
111
112		@tparam T The result type. Use `task<>` for `task<void>`.
113
114		@see ContextRunnable, ContextAwaitable, run, run_async
115		*/
116		template<typename T = void>
117		struct [[nodiscard]] BOOST_CAPY_CORO_AWAIT_ELIDABLE
118		task
119		{
120		/** Stores `task<T>`'s result and joins the I/O awaitable protocol via `context_awaitable_promise_base`.
121
122		This is the promise object the compiler associates with a
123		`task<T>` coroutine. It satisfies the coroutine promise
124		requirements and participates in the I/O awaitable protocol via
125		@ref context_awaitable_promise_base. It is part of the coroutine
126		machinery and is not intended to be used directly by callers.
127
128		Result storage and `return_value`/`return_void` are provided by
129		`detail::task_return_base<T>`.
130
131		@see context_awaitable_promise_base, ContextRunnable
132		*/
133		struct promise_type
134		: context_awaitable_promise_base<promise_type>
135		, detail::task_return_base<T>
136		{
137		private:
138		friend task;
139		union { std::exception_ptr ep_; };
140		bool has_ep_;
141
142		public:
143		/// Construct the promise with no stored exception.
144	112700x	promise_type() noexcept
145	112700x	: has_ep_(false)
146		{
147	112700x	}
148
149		/// Destroy the promise, releasing any stored exception.
150	112700x	~promise_type()
151		{
152	112700x	if(has_ep_)
153	490x	ep_.~exception_ptr();
154	112700x	}
155
156		/** Return the exception captured by the coroutine body, if any.
157
158		@return The stored exception, or a null `std::exception_ptr`
159		if the coroutine did not exit via an unhandled exception.
160		*/
161	4512x	std::exception_ptr exception() const noexcept
162		{
163	4512x	if(has_ep_)
164	732x	return ep_;
165	3780x	return {};
166		}
167
168		/** Return the owning `task` for this coroutine.
169
170		Called by the compiler to produce the object returned to the
171		caller when the coroutine is created.
172
173		@return A `task` owning the coroutine frame.
174		*/
175	112700x	task get_return_object()
176		{
177	112700x	return task{std::coroutine_handle<promise_type>::from_promise(*this)};
178		}
179
180		/** Return the initial-suspend awaiter.
181
182		The coroutine always suspends at the initial suspend point,
183		so the body does not start until the task is awaited. When the
184		body is resumed, the awaiter restores the thread-local frame
185		allocator from the stored environment.
186
187		@return An awaiter that suspends unconditionally.
188		*/
189	112700x	auto initial_suspend() noexcept
190		{
191		struct awaiter
192		{
193		promise_type* p_;
194
195	360x	bool await_ready() const noexcept
196		{
197	360x	return false;
198		}
199
200	360x	void await_suspend(std::coroutine_handle<>) const noexcept
201		{
202	360x	}
203
204	359x	void await_resume() const noexcept
205		{
206		// Restore TLS when body starts executing
207	359x	set_current_frame_allocator(p_->environment()->frame_allocator);
208	359x	}
209		};
210	112700x	return awaiter{this};
211		}
212
213		/** Return the final-suspend awaiter.
214
215		The coroutine always suspends at the final suspend point. The
216		awaiter's `await_suspend` performs symmetric transfer to the
217		stored continuation (consuming it), resuming the awaiting
218		coroutine.
219
220		@return An awaiter that suspends and transfers to the
221		continuation.
222		*/
223	5013x	auto final_suspend() noexcept
224		{
225		struct awaiter
226		{
227		promise_type* p_;
228
229	358x	bool await_ready() const noexcept
230		{
231	358x	return false;
232		}
233
234	358x	std::coroutine_handle<> await_suspend(std::coroutine_handle<>) const noexcept
235		{
236	358x	return p_->continuation();
237		}
238
239	−	void await_resume() const noexcept {} // LCOV_EXCL_LINE final_suspend awaiter, never resumed
240		};
241	5013x	return awaiter{this};
242		}
243
244		/** Capture the in-flight exception from the coroutine body.
245
246		Called by the compiler when the coroutine body exits via an
247		unhandled exception. The captured exception is rethrown when
248		the task is awaited.
249		*/
250	490x	void unhandled_exception() noexcept
251		{
252	490x	new (&ep_) std::exception_ptr(std::current_exception());
253	490x	has_ep_ = true;
254	490x	}
255
256		/** Awaiter wrapping a nested `co_await` of an @ref ContextAwaitable.
257
258		Forwards the environment to the inner awaitable's
259		environment-taking `await_suspend` and restores the
260		thread-local frame allocator before the body resumes.
261
262		@tparam Awaitable The awaitable being transformed.
263		*/
264		template<class Awaitable>
265		struct transform_awaiter
266		{
267		/// The wrapped awaitable, decayed and stored by value.
268		std::decay_t<Awaitable> a_;
269
270		/// The promise of the coroutine performing the `co_await`.
271		promise_type* p_;
272
273		/** Report whether the wrapped awaitable is already complete.
274
275		@return The wrapped awaitable's own `await_ready` result:
276		`true` if no suspension is needed.
277		*/
278	107722x	bool await_ready() noexcept
279		{
280	107722x	return a_.await_ready();
281		}
282
283		/** Restore the frame allocator, then resume the wrapped
284		awaitable.
285
286		Reinstalls the thread-local frame allocator from the stored
287		environment before the body continues. This is needed
288		because the resumption may arrive on a different thread
289		than the one that suspended.
290
291		@return The wrapped awaitable's await-result, forwarded
292		unchanged.
293		*/
294	5084x	decltype(auto) await_resume()
295		{
296		// Restore TLS before body resumes
297	5084x	set_current_frame_allocator(p_->environment()->frame_allocator);
298	5084x	return a_.await_resume();
299		}
300
301		/** Suspend by calling the wrapped awaitable with the
302		environment.
303
304		This is the plain `await_suspend` the compiler calls for the
305		nested `co_await`. It forwards to the wrapped awaitable's
306		@ref ContextAwaitable overload, supplying the promise's stored
307		environment as the second argument. It then hands back
308		that call's result unchanged, so the wrapped awaitable's
309		suspension decision, whatever form it takes, is preserved.
310
311		@param h The coroutine performing the `co_await`.
312
313		@return Whatever the wrapped awaitable's `await_suspend`
314		returns. When that is a `std::coroutine_handle<>`, the
315		handle is routed through `detail::symmetric_transfer`.
316		On MSVC that helper resumes the handle on the current
317		stack, and this function returns `void`, so the awaiting
318		coroutine suspends unconditionally. On every other
319		compiler the handle is returned unchanged for symmetric
320		transfer.
321		*/
322		template<class Promise>
323	107102x	auto await_suspend(std::coroutine_handle<Promise> h) noexcept
324		{
325		using R = decltype(a_.await_suspend(h, p_->environment()));
326		if constexpr (std::is_same_v<R, std::coroutine_handle<>>)
327	106071x	return detail::symmetric_transfer(a_.await_suspend(h, p_->environment()));
328		else
329	1031x	return a_.await_suspend(h, p_->environment());
330		}
331		};
332
333		/** Transform a nested awaitable before `co_await`.
334
335		Wraps an @ref ContextAwaitable in a @ref transform_awaiter so the
336		coroutine's environment is propagated into it. A diagnostic
337		is emitted if the awaitable does not satisfy @ref ContextAwaitable.
338
339		@param a The awaitable expression from `co_await a`.
340
341		@return A @ref transform_awaiter wrapping `a`.
342		*/
343		template<class Awaitable>
344	107722x	auto transform_awaitable(Awaitable&& a)
345		{
346		using A = std::decay_t<Awaitable>;
347		if constexpr (ContextAwaitable<A>)
348		{
349		return transform_awaiter<Awaitable>{
350	212933x	std::forward<Awaitable>(a), this};
351		}
352		else
353		{
354		static_assert(ContextAwaitable<A>, "requires ContextAwaitable");
355		}
356	105211x	}
357		};
358
359		/** Handle to the owned coroutine frame.
360
361		Null when the task is empty (for example after a move or after
362		@ref release). Prefer @ref handle to read this; the member is
363		public for use by the coroutine machinery.
364		*/
365		std::coroutine_handle<promise_type> h_;
366
367		/** Destroy the task and its coroutine frame if owned.
368
369		@par Preconditions
370		The frame is not lent: no parent is suspended awaiting it,
371		unless its chain is being unwound after an @ref abandon.
372		Destroying a lent frame otherwise calls `std::terminate`; end
373		a running chain by requesting stop, or by destroying its
374		execution context.
375		*/
376	116770x	~task()
377		{
378	116770x	destroy_frame();
379	116770x	}
380
381		/** Report whether the awaited task is already complete.
382
383		Always returns `false`; a task is lazy and has not started when
384		it is awaited, so the awaiting coroutine always suspends.
385
386		@return `false`.
387		*/
388	2104x	bool await_ready() const noexcept
389		{
390	2104x	return false;
391		}
392
393		/** Return the task's result, rethrowing any captured exception.
394
395		If the coroutine body exited via an unhandled exception, that
396		exception is rethrown here. Otherwise the result is returned by
397		move (for `task<T>`) or nothing is returned (for `task<void>`).
398
399		@return The result value for non-void `T`; otherwise `void`.
400
401		@throws The exception captured by the coroutine body, if any.
402
403		@note Discarding a `results` silently drops the error
404		code, so that overload is marked `[[nodiscard]]`.
405		*/
406	562x	[[nodiscard]] auto await_resume()
407		requires detail::is_results_v<T>
408		{
409	562x	lent_ = false;
410	562x	if(h_.promise().has_ep_)
411	105x	std::rethrow_exception(h_.promise().ep_);
412	457x	return std::move(*h_.promise().result_);
413		}
414
415	242x	auto await_resume()
416		requires (! detail::is_results_v<T>)
417		{
418	242x	lent_ = false;
419	242x	if(h_.promise().has_ep_)
420	18x	std::rethrow_exception(h_.promise().ep_);
421		if constexpr (! std::is_void_v<T>)
422	151x	return std::move(*h_.promise().result_);
423		else
424	73x	return;
425		}
426
427		/** Start the task with the awaiting coroutine's context.
428
429		Stores `cont` as the continuation to resume on completion.
430		Stores `env` as the execution environment propagated to nested
431		`co_await` expressions. Then transfers control into the task's
432		coroutine body via the returned handle.
433
434		@param cont The awaiting coroutine to resume when the task
435		completes.
436
437		@param env The execution environment (executor, stop token, and
438		frame allocator). It must outlive the task.
439
440		@return The task's coroutine handle, for symmetric transfer.
441		*/
442	2001x	std::coroutine_handle<> await_suspend(std::coroutine_handle<> cont, await_context const* env)
443		{
444	2001x	h_.promise().set_continuation(cont);
445	2001x	h_.promise().set_environment(env);
446	2001x	lent_ = true;
447	2001x	return h_;
448		}
449
450		/** Return the coroutine handle.
451
452		@note Do not call `destroy()` on the returned handle while the
453		task is being awaited: the awaiting frame still holds it and
454		destroys it again, which has undefined behavior. A holder that
455		gives the coroutine up passes its continuation to @ref abandon
456		instead. (Destroying or
457		move-assigning over the task object itself while its frame is
458		lent is a different operation, and calls `std::terminate`.)
459		The task's lifetime is normally managed by `run_async`, `run`,
460		or the awaiting parent. For cooperative cancellation, use
461		`std::stop_token`.
462
463		@note The operation, queue or primitive holding a suspended
464		coroutine gives it up with @ref abandon, through the
465		continuation it keeps, never by destroying a handle.
466		`handle()` belongs to the owning task object.
467
468		@return The coroutine handle.
469		*/
470	110728x	std::coroutine_handle<promise_type> handle() const noexcept
471		{
472	110728x	return h_;
473		}
474
475		/** Release ownership of the coroutine frame.
476
477		After calling this, destroying the task does not destroy the
478		coroutine frame. The caller becomes responsible for the frame's
479		lifetime.
480
481		@note The caller may call `destroy()` on the released handle
482		only when the task has not started or has fully completed.
483		Destroying the released handle of a task that is being
484		awaited is not supported and has undefined behavior.
485
486		@par Postconditions
487		`handle()` returns a null handle. Callers needing the
488		original handle must save it, via @ref handle, before
489		calling this.
490		*/
491	110585x	void release() noexcept
492		{
493	110585x	h_ = nullptr;
494	110585x	}
495
496		/** Copy construction is disabled; a task uniquely owns its frame.
497
498		@param other The task that would be copied.
499		*/
500		task(task const& other) = delete;
501
502		/** Copy assignment is disabled; a task uniquely owns its frame.
503
504		@param other The task that would be assigned from.
505
506		@return A reference to `*this`.
507		*/
508		task& operator=(task const& other) = delete;
509
510		/** Construct by moving, transferring ownership of the frame.
511
512		@par Postconditions
513		`other` is empty and must not be awaited.
514
515		@param other The task to move from.
516		*/
517	4070x	task(task&& other) noexcept
518	4070x	: h_(std::exchange(other.h_, nullptr))
519		{
520	4070x	}
521
522		/** Assign by moving, transferring ownership of the frame.
523
524		If this task already owns a coroutine frame, that frame is
525		destroyed first. Self-assignment is a no-op.
526
527		@par Preconditions
528		The frame being replaced is not lent: no parent is suspended
529		awaiting it. Replacing a lent frame calls `std::terminate`.
530
531		@par Postconditions
532		`other` is empty and must not be awaited.
533
534		@param other The task to move from.
535
536		@return A reference to `*this`.
537		*/
538	1x	task& operator=(task&& other) noexcept
539		{
540	1x	if(this != &other)
541		{
542	1x	destroy_frame();
543	1x	h_ = std::exchange(other.h_, nullptr);
544		}
545	1x	return *this;
546		}
547
548		private:
549		// Set while a parent is suspended awaiting this task.
550		bool lent_ = false;
551
552	112700x	explicit task(std::coroutine_handle<promise_type> h)
553	112700x	: h_(h)
554		{
555	112700x	}
556
557	116771x	void destroy_frame() noexcept
558		{
559	116771x	if(!h_)
560	114656x	return;
561	2115x	if(lent_ && !h_.done())
562		{
563		// Only the unwind of an abandoned chain destroys a frame
564		// that is still awaited.
565	1278x	auto* owner = h_.promise().environment()->owner;
566	1278x	if(!owner \|\| !owner->abandoned())
567	−	std::terminate(); // LCOV_EXCL_LINE reached only in a death test's child process
568		}
569	2115x	std::exchange(h_, nullptr).destroy();
570	2115x	lent_ = false;
571		}
572		};
573
574		} // namespace capy
575		} // namespace boost
576
577		#endif
578