include/boost/capy/task.hpp

100.0% Lines (95 / 95, 2 excl) 92.1% Functions (1344 / 1459, 3 excl)

[ ] prev/next file

task.hpp

f(x) Functions (1462)

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	904x	void return_value(T value)
41		{
42	904x	result_ = std::move(value);
43	904x	}
44
45	283x	T&& result() noexcept
46		{
47	283x	return std::move(*result_);
48		}
49		};
50
51		template<>
52		struct task_return_base<void>
53		{
54	4097x	void return_void()
55		{
56	4097x	}
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 @ref ContextRunnable, @ref ContextAwaitable, @ref run, @ref 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 @ref context_awaitable_promise_base, @ref 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	109232x	promise_type() noexcept
145	109232x	: has_ep_(false)
146		{
147	109232x	}
148
149		/// Destroy the promise, releasing any stored exception.
150	109232x	~promise_type()
151		{
152	109232x	if(has_ep_)
153	490x	ep_.~exception_ptr();
154	109232x	}
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	4977x	std::exception_ptr exception() const noexcept
162		{
163	4977x	if(has_ep_)
164	732x	return ep_;
165	4245x	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	109232x	task get_return_object()
176		{
177	109232x	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	109232x	auto initial_suspend() noexcept
190		{
191		struct awaiter
192		{
193		promise_type* p_;
194
195	30x	bool await_ready() const noexcept
196		{
197	30x	return false;
198		}
199
200	30x	void await_suspend(std::coroutine_handle<>) const noexcept
201		{
202	30x	}
203
204	30x	void await_resume() const noexcept
205		{
206		// Restore TLS when body starts executing
207	30x	set_current_frame_allocator(p_->environment()->frame_allocator);
208	30x	}
209		};
210	109232x	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	5491x	auto final_suspend() noexcept
224		{
225		struct awaiter
226		{
227		promise_type* p_;
228
229	30x	bool await_ready() const noexcept
230		{
231	30x	return false;
232		}
233
234	30x	std::coroutine_handle<> await_suspend(std::coroutine_handle<>) const noexcept
235		{
236	30x	return p_->continuation();
237		}
238
239	−	void await_resume() const noexcept {} // LCOV_EXCL_LINE final_suspend awaiter, never resumed
240		};
241	5491x	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		Where `BOOST_CAPY_SYMMETRIC_TRANSFER_WORKAROUND` is on,
276		this always returns `false`, and @ref await_suspend asks
277		the wrapped awaitable instead. See
278		`detail::await_ready_then_suspend`.
279
280		@return The wrapped awaitable's own `await_ready` result:
281		`true` if no suspension is needed. Always `false` where
282		the workaround is on.
283		*/
284	108222x	bool await_ready() noexcept
285		{
286		#if BOOST_CAPY_SYMMETRIC_TRANSFER_WORKAROUND
287		return false;
288		#else
289	108222x	return a_.await_ready();
290		#endif
291		}
292
293		/** Restore the frame allocator, then resume the wrapped
294		awaitable.
295
296		Reinstalls the thread-local frame allocator from the stored
297		environment before the body continues. This is needed
298		because the resumption may arrive on a different thread
299		than the one that suspended.
300
301		@return The wrapped awaitable's await-result, forwarded
302		unchanged.
303		*/
304	5564x	decltype(auto) await_resume()
305		{
306		// Restore TLS before body resumes
307	5564x	set_current_frame_allocator(p_->environment()->frame_allocator);
308	5564x	return a_.await_resume();
309		}
310
311		/** Suspend by calling the wrapped awaitable with the
312		environment.
313
314		This is the plain `await_suspend` the compiler calls for the
315		nested `co_await`. It forwards to the wrapped awaitable's
316		@ref ContextAwaitable overload, supplying the promise's stored
317		environment as the second argument. It then hands back
318		that call's result unchanged, so the wrapped awaitable's
319		suspension decision, whatever form it takes, is preserved.
320
321		@param h The coroutine performing the `co_await`.
322
323		@return Whatever the wrapped awaitable's `await_suspend`
324		returns. When that is a `std::coroutine_handle<>`, the
325		handle is routed through `detail::symmetric_transfer`.
326		Where `BOOST_CAPY_SYMMETRIC_TRANSFER_WORKAROUND` is on,
327		this function instead returns `bool` from
328		`detail::await_ready_then_suspend`. It first asks the
329		wrapped awaitable's `await_ready`. When that reports
330		ready, it returns `false` to continue without
331		suspending. Otherwise it resumes any returned handle on
332		the current stack and returns `true`. Where the
333		workaround is off, a returned handle is passed back
334		unchanged for symmetric transfer.
335		*/
336		template<class Promise>
337	107666x	auto await_suspend(std::coroutine_handle<Promise> h) noexcept
338		{
339		#if BOOST_CAPY_SYMMETRIC_TRANSFER_WORKAROUND
340		return detail::await_ready_then_suspend(a_, h, p_->environment());
341		#else
342		using R = decltype(a_.await_suspend(h, p_->environment()));
343		if constexpr (std::is_same_v<R, std::coroutine_handle<>>)
344	106624x	return detail::symmetric_transfer(a_.await_suspend(h, p_->environment()));
345		else
346	1042x	return a_.await_suspend(h, p_->environment());
347		#endif
348		}
349		};
350
351		/** Transform a nested awaitable before `co_await`.
352
353		Wraps an @ref ContextAwaitable in a @ref transform_awaiter so the
354		coroutine's environment is propagated into it. A diagnostic
355		is emitted if the awaitable does not satisfy @ref ContextAwaitable.
356
357		@param a The awaitable expression from `co_await a`.
358
359		@return A @ref transform_awaiter wrapping `a`.
360		*/
361		template<class Awaitable>
362	108222x	auto transform_awaitable(Awaitable&& a)
363		{
364		using A = std::decay_t<Awaitable>;
365		if constexpr (ContextAwaitable<A>)
366		{
367		return transform_awaiter<Awaitable>{
368	213919x	std::forward<Awaitable>(a), this};
369		}
370		else
371		{
372		static_assert(ContextAwaitable<A>, "requires ContextAwaitable");
373		}
374	105697x	}
375		};
376
377		/** Handle to the owned coroutine frame.
378
379		Null when the task is empty (for example after a move or after
380		@ref release). Prefer @ref handle to read this; the member is
381		public for use by the coroutine machinery.
382		*/
383		std::coroutine_handle<promise_type> h_;
384
385		/** Destroy the task and its coroutine frame if owned.
386
387		@par Preconditions
388		The frame is not lent: no parent is suspended awaiting it,
389		unless its chain is being unwound after an @ref abandon.
390		Destroying a lent frame otherwise calls `std::terminate`; end
391		a running chain by requesting stop, or by destroying its
392		execution context.
393		*/
394	113320x	~task()
395		{
396	113320x	destroy_frame();
397	113320x	}
398
399		/** Report whether the awaited task is already complete.
400
401		Always returns `false`; a task is lazy and has not started when
402		it is awaited, so the awaiting coroutine always suspends.
403
404		@return `false`.
405		*/
406	2117x	bool await_ready() const noexcept
407		{
408	2117x	return false;
409		}
410
411		/** Return the task's result, rethrowing any captured exception.
412
413		If the coroutine body exited via an unhandled exception, that
414		exception is rethrown here. Otherwise the result is returned by
415		move (for `task<T>`) or nothing is returned (for `task<void>`).
416
417		@return The result value for non-void `T`; otherwise `void`.
418
419		@throws The exception captured by the coroutine body, if any.
420
421		@note Discarding a `results` silently drops the error
422		code, so that overload is marked `[[nodiscard]]`.
423		*/
424	570x	[[nodiscard]] auto await_resume()
425		requires detail::is_results_v<T>
426		{
427	570x	lent_ = false;
428	570x	if(h_.promise().has_ep_)
429	105x	std::rethrow_exception(h_.promise().ep_);
430	465x	return std::move(*h_.promise().result_);
431		}
432
433	247x	auto await_resume()
434		requires (! detail::is_results_v<T>)
435		{
436	247x	lent_ = false;
437	247x	if(h_.promise().has_ep_)
438	18x	std::rethrow_exception(h_.promise().ep_);
439		if constexpr (! std::is_void_v<T>)
440	154x	return std::move(*h_.promise().result_);
441		else
442	75x	return;
443		}
444
445		/** Start the task with the awaiting coroutine's context.
446
447		Stores `cont` as the continuation to resume on completion.
448		Stores `env` as the execution environment propagated to nested
449		`co_await` expressions. Then transfers control into the task's
450		coroutine body via the returned handle.
451
452		@param cont The awaiting coroutine to resume when the task
453		completes.
454
455		@param env The execution environment (executor, stop token, and
456		frame allocator). It must outlive the task.
457
458		@return The task's coroutine handle, for symmetric transfer.
459		*/
460	2014x	std::coroutine_handle<> await_suspend(std::coroutine_handle<> cont, await_context const* env)
461		{
462	2014x	h_.promise().set_continuation(cont);
463	2014x	h_.promise().set_environment(env);
464	2014x	lent_ = true;
465	2014x	return h_;
466		}
467
468		/** Return the coroutine handle.
469
470		@note Do not call `destroy()` on the returned handle while the
471		task is being awaited: the awaiting frame still holds it and
472		destroys it again, which has undefined behavior. A holder that
473		gives the coroutine up passes its continuation to @ref abandon
474		instead. (Destroying or
475		move-assigning over the task object itself while its frame is
476		lent is a different operation, and calls `std::terminate`.)
477		The task's lifetime is normally managed by `run_async`, `run`,
478		or the awaiting parent. For cooperative cancellation, use
479		`std::stop_token`.
480
481		@note The operation, queue or primitive holding a suspended
482		coroutine gives it up with @ref abandon, through the
483		continuation it keeps, never by destroying a handle.
484		`handle()` belongs to the owning task object.
485
486		@return The coroutine handle.
487		*/
488	107247x	std::coroutine_handle<promise_type> handle() const noexcept
489		{
490	107247x	return h_;
491		}
492
493		/** Release ownership of the coroutine frame.
494
495		After calling this, destroying the task does not destroy the
496		coroutine frame. The caller becomes responsible for the frame's
497		lifetime.
498
499		@note The caller may call `destroy()` on the released handle
500		only when the task has not started or has fully completed.
501		Destroying the released handle of a task that is being
502		awaited is not supported and has undefined behavior.
503
504		@par Postconditions
505		`handle()` returns a null handle. Callers needing the
506		original handle must save it, via @ref handle, before
507		calling this.
508		*/
509	107104x	void release() noexcept
510		{
511	107104x	h_ = nullptr;
512	107104x	}
513
514		/** Copy construction is disabled; a task uniquely owns its frame.
515
516		@param other The task that would be copied.
517		*/
518		task(task const& other) = delete;
519
520		/** Copy assignment is disabled; a task uniquely owns its frame.
521
522		@param other The task that would be assigned from.
523
524		@return A reference to `*this`.
525		*/
526		task& operator=(task const& other) = delete;
527
528		/** Construct by moving, transferring ownership of the frame.
529
530		@par Postconditions
531		`other` is empty and must not be awaited.
532
533		@param other The task to move from.
534		*/
535	4088x	task(task&& other) noexcept
536	4088x	: h_(std::exchange(other.h_, nullptr))
537		{
538	4088x	}
539
540		/** Assign by moving, transferring ownership of the frame.
541
542		If this task already owns a coroutine frame, that frame is
543		destroyed first. Self-assignment is a no-op.
544
545		@par Preconditions
546		The frame being replaced is not lent: no parent is suspended
547		awaiting it. Replacing a lent frame calls `std::terminate`.
548
549		@par Postconditions
550		`other` is empty and must not be awaited.
551
552		@param other The task to move from.
553
554		@return A reference to `*this`.
555		*/
556	1x	task& operator=(task&& other) noexcept
557		{
558	1x	if(this != &other)
559		{
560	1x	destroy_frame();
561	1x	h_ = std::exchange(other.h_, nullptr);
562		}
563	1x	return *this;
564		}
565
566		private:
567		// Set while a parent is suspended awaiting this task.
568		bool lent_ = false;
569
570	109232x	explicit task(std::coroutine_handle<promise_type> h)
571	109232x	: h_(h)
572		{
573	109232x	}
574
575	113321x	void destroy_frame() noexcept
576		{
577	113321x	if(!h_)
578	111193x	return;
579	2128x	if(lent_ && !h_.done())
580		{
581		// Only the unwind of an abandoned chain destroys a frame
582		// that is still awaited.
583	1278x	auto* owner = h_.promise().environment()->owner;
584	1278x	if(!owner \|\| !owner->abandoned())
585	−	std::terminate(); // LCOV_EXCL_LINE reached only in a death test's child process
586		}
587	2128x	std::exchange(h_, nullptr).destroy();
588	2128x	lent_ = false;
589		}
590		};
591
592		} // namespace capy
593		} // namespace boost
594
595		#endif
596