include/boost/capy/task.hpp

100.0% Lines (80/1/81) 95.0% List of functions (1241/2/1308)

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

task.hpp

f(x) Functions (1308)

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/io_awaitable.hpp>
17		#include <boost/capy/ex/io_awaitable_promise_base.hpp>
18		#include <boost/capy/ex/io_env.hpp>
19		#include <boost/capy/ex/frame_allocator.hpp>
20		#include <boost/capy/detail/await_suspend_helper.hpp>
21		#include <boost/capy/io_result.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	870x	void return_value(T value)
41		{
42	870x	result_ = std::move(value);
43	870x	}
44
45	273x	T&& result() noexcept
46		{
47	273x	return std::move(*result_);
48		}
49		};
50
51		template<>
52		struct task_return_base<void>
53		{
54	1264x	void return_void()
55		{
56	1264x	}
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		@code
110		task<int> compute_value()
111		{
112		auto [ec, n] = co_await stream.read_some( buf );
113		if( ec )
114		co_return 0;
115		co_return process( buf, n );
116		}
117
118		task<> run_session( tcp_socket sock )
119		{
120		int result = co_await compute_value();
121		// ...
122		}
123		@endcode
124
125		@tparam T The result type. Use `task<>` for `task<void>`.
126
127		@see IoRunnable, IoAwaitable, run, run_async
128		*/
129		template<typename T = void>
130		struct [[nodiscard]] BOOST_CAPY_CORO_AWAIT_ELIDABLE
131		task
132		{
133		/** Stores `task<T>`'s result and joins the I/O awaitable protocol via `io_awaitable_promise_base`.
134
135		This is the promise object the compiler associates with a
136		`task<T>` coroutine. It satisfies the coroutine promise
137		requirements and participates in the I/O awaitable protocol via
138		@ref io_awaitable_promise_base. It is part of the coroutine
139		machinery and is not intended to be used directly by callers.
140
141		Result storage and `return_value`/`return_void` are provided by
142		`detail::task_return_base<T>`.
143
144		@see io_awaitable_promise_base, IoRunnable
145		*/
146		struct promise_type
147		: io_awaitable_promise_base<promise_type>
148		, detail::task_return_base<T>
149		{
150		private:
151		friend task;
152		union { std::exception_ptr ep_; };
153		bool has_ep_;
154
155		public:
156		/// Construct the promise with no stored exception.
157	2772x	promise_type() noexcept
158	2772x	: has_ep_(false)
159		{
160	2772x	}
161
162		/// Destroy the promise, releasing any stored exception.
163	2772x	~promise_type()
164		{
165	2772x	if(has_ep_)
166	489x	ep_.~exception_ptr();
167	2772x	}
168
169		/** Return the exception captured by the coroutine body, if any.
170
171		@return The stored exception, or a null `std::exception_ptr`
172		if the coroutine did not exit via an unhandled exception.
173		*/
174	2164x	std::exception_ptr exception() const noexcept
175		{
176	2164x	if(has_ep_)
177	730x	return ep_;
178	1434x	return {};
179		}
180
181		/** Return the owning `task` for this coroutine.
182
183		Called by the compiler to produce the object returned to the
184		caller when the coroutine is created.
185
186		@return A `task` owning the coroutine frame.
187		*/
188	2772x	task get_return_object()
189		{
190	2772x	return task{std::coroutine_handle<promise_type>::from_promise(*this)};
191		}
192
193		/** Return the initial-suspend awaiter.
194
195		The coroutine always suspends at the initial suspend point,
196		so the body does not start until the task is awaited. When the
197		body is resumed, the awaiter restores the thread-local frame
198		allocator from the stored environment.
199
200		@return An awaiter that suspends unconditionally.
201		*/
202	2772x	auto initial_suspend() noexcept
203		{
204		struct awaiter
205		{
206		promise_type* p_;
207
208	520x	bool await_ready() const noexcept
209		{
210	520x	return false;
211		}
212
213	520x	void await_suspend(std::coroutine_handle<>) const noexcept
214		{
215	520x	}
216
217	519x	void await_resume() const noexcept
218		{
219		// Restore TLS when body starts executing
220	519x	set_current_frame_allocator(p_->environment()->frame_allocator);
221	519x	}
222		};
223	2772x	return awaiter{this};
224		}
225
226		/** Return the final-suspend awaiter.
227
228		The coroutine always suspends at the final suspend point. The
229		awaiter's `await_suspend` performs symmetric transfer to the
230		stored continuation (consuming it), resuming the awaiting
231		coroutine.
232
233		@return An awaiter that suspends and transfers to the
234		continuation.
235		*/
236	2623x	auto final_suspend() noexcept
237		{
238		struct awaiter
239		{
240		promise_type* p_;
241
242	519x	bool await_ready() const noexcept
243		{
244	519x	return false;
245		}
246
247	519x	std::coroutine_handle<> await_suspend(std::coroutine_handle<>) const noexcept
248		{
249	519x	return p_->continuation();
250		}
251
252	−	void await_resume() const noexcept {} // LCOV_EXCL_LINE final_suspend awaiter, never resumed
253		};
254	2623x	return awaiter{this};
255		}
256
257		/** Capture the in-flight exception from the coroutine body.
258
259		Called by the compiler when the coroutine body exits via an
260		unhandled exception. The captured exception is rethrown when
261		the task is awaited.
262		*/
263	489x	void unhandled_exception() noexcept
264		{
265	489x	new (&ep_) std::exception_ptr(std::current_exception());
266	489x	has_ep_ = true;
267	489x	}
268
269		/** Awaiter wrapping a nested `co_await` of an @ref IoAwaitable.
270
271		Forwards the environment to the inner awaitable's
272		environment-taking `await_suspend` and restores the
273		thread-local frame allocator before the body resumes.
274
275		@tparam Awaitable The awaitable being transformed.
276		*/
277		template<class Awaitable>
278		struct transform_awaiter
279		{
280		/// The wrapped awaitable, decayed and stored by value.
281		std::decay_t<Awaitable> a_;
282
283		/// The promise of the coroutine performing the `co_await`.
284		promise_type* p_;
285
286		/** Report whether the wrapped awaitable is already complete.
287
288		@return The wrapped awaitable's own `await_ready` result:
289		`true` if no suspension is needed.
290		*/
291	2883x	bool await_ready() noexcept
292		{
293	2883x	return a_.await_ready();
294		}
295
296		/** Restore the frame allocator, then resume the wrapped
297		awaitable.
298
299		Reinstalls the thread-local frame allocator from the stored
300		environment before the body continues. This is needed
301		because the resumption may arrive on a different thread
302		than the one that suspended.
303
304		@return The wrapped awaitable's await-result, forwarded
305		unchanged.
306		*/
307	2738x	decltype(auto) await_resume()
308		{
309		// Restore TLS before body resumes
310	2738x	set_current_frame_allocator(p_->environment()->frame_allocator);
311	2738x	return a_.await_resume();
312		}
313
314		/** Suspend by calling the wrapped awaitable with the
315		environment.
316
317		This is the plain `await_suspend` the compiler calls for the
318		nested `co_await`. It forwards to the wrapped awaitable's
319		@ref IoAwaitable overload, supplying the promise's stored
320		environment as the second argument. It then hands back
321		that call's result unchanged, so the wrapped awaitable's
322		suspension decision, whatever form it takes, is preserved.
323
324		@param h The coroutine performing the `co_await`.
325
326		@return Whatever the wrapped awaitable's `await_suspend`
327		returns. When that is a `std::coroutine_handle<>`, the
328		handle is routed through `detail::symmetric_transfer`.
329		On MSVC that helper resumes the handle on the current
330		stack, and this function returns `void`, so the awaiting
331		coroutine suspends unconditionally. On every other
332		compiler the handle is returned unchanged for symmetric
333		transfer.
334		*/
335		template<class Promise>
336	2263x	auto await_suspend(std::coroutine_handle<Promise> h) noexcept
337		{
338		using R = decltype(a_.await_suspend(h, p_->environment()));
339		if constexpr (std::is_same_v<R, std::coroutine_handle<>>)
340	1263x	return detail::symmetric_transfer(a_.await_suspend(h, p_->environment()));
341		else
342	1000x	return a_.await_suspend(h, p_->environment());
343		}
344		};
345
346		/** Transform a nested awaitable before `co_await`.
347
348		Wraps an @ref IoAwaitable in a @ref transform_awaiter so the
349		coroutine's environment is propagated into it. A diagnostic
350		is emitted if the awaitable does not satisfy @ref IoAwaitable.
351
352		@param a The awaitable expression from `co_await a`.
353
354		@return A @ref transform_awaiter wrapping `a`.
355		*/
356		template<class Awaitable>
357	2883x	auto transform_awaitable(Awaitable&& a)
358		{
359		using A = std::decay_t<Awaitable>;
360		if constexpr (IoAwaitable<A>)
361		{
362		return transform_awaiter<Awaitable>{
363	4420x	std::forward<Awaitable>(a), this};
364		}
365		else
366		{
367		static_assert(IoAwaitable<A>, "requires IoAwaitable");
368		}
369	1537x	}
370		};
371
372		/** Handle to the owned coroutine frame.
373
374		Null when the task is empty (for example after a move or after
375		@ref release). Prefer @ref handle to read this; the member is
376		public for use by the coroutine machinery.
377		*/
378		std::coroutine_handle<promise_type> h_;
379
380		/// Destroy the task and its coroutine frame if owned.
381	5862x	~task()
382		{
383	5862x	if(h_)
384	767x	h_.destroy();
385	5862x	}
386
387		/** Report whether the awaited task is already complete.
388
389		Always returns `false`; a task is lazy and has not started when
390		it is awaited, so the awaiting coroutine always suspends.
391
392		@return `false`.
393		*/
394	764x	bool await_ready() const noexcept
395		{
396	764x	return false;
397		}
398
399		/** Return the task's result, rethrowing any captured exception.
400
401		If the coroutine body exited via an unhandled exception, that
402		exception is rethrown here. Otherwise the result is returned by
403		move (for `task<T>`) or nothing is returned (for `task<void>`).
404
405		@return The result value for non-void `T`; otherwise `void`.
406
407		@throws The exception captured by the coroutine body, if any.
408
409		@note Discarding an `io_result` silently drops the error
410		code, so that overload is marked `[[nodiscard]]`.
411		*/
412	552x	[[nodiscard]] auto await_resume()
413		requires detail::is_io_result_v<T>
414		{
415	552x	if(h_.promise().has_ep_)
416	105x	std::rethrow_exception(h_.promise().ep_);
417	447x	return std::move(*h_.promise().result_);
418		}
419
420	211x	auto await_resume()
421		requires (! detail::is_io_result_v<T>)
422		{
423	211x	if(h_.promise().has_ep_)
424	18x	std::rethrow_exception(h_.promise().ep_);
425		if constexpr (! std::is_void_v<T>)
426	148x	return std::move(*h_.promise().result_);
427		else
428	45x	return;
429		}
430
431		/** Start the task with the awaiting coroutine's context.
432
433		Stores `cont` as the continuation to resume on completion.
434		Stores `env` as the execution environment propagated to nested
435		`co_await` expressions. Then transfers control into the task's
436		coroutine body via the returned handle.
437
438		@param cont The awaiting coroutine to resume when the task
439		completes.
440
441		@param env The execution environment (executor, stop token, and
442		frame allocator). It must outlive the task.
443
444		@return The task's coroutine handle, for symmetric transfer.
445		*/
446	683x	std::coroutine_handle<> await_suspend(std::coroutine_handle<> cont, io_env const* env)
447		{
448	683x	h_.promise().set_continuation(cont);
449	683x	h_.promise().set_environment(env);
450	683x	return h_;
451		}
452
453		/** Return the coroutine handle.
454
455		@note Do not call `destroy()` on the returned handle while the
456		task is being awaited. The task's lifetime is normally managed
457		by `run_async`, `run`, or the awaiting parent. Manually
458		destroying a suspended task that another coroutine is awaiting
459		produces undefined behavior. For cooperative cancellation, use
460		`std::stop_token`.
461
462		@return The coroutine handle.
463		*/
464	2088x	std::coroutine_handle<promise_type> handle() const noexcept
465		{
466	2088x	return h_;
467		}
468
469		/** Release ownership of the coroutine frame.
470
471		After calling this, destroying the task does not destroy the
472		coroutine frame. The caller becomes responsible for the frame's
473		lifetime.
474
475		@note The caller may call `destroy()` on the released handle
476		only when the task has not started or has fully completed.
477		Destroying a suspended task that is being awaited produces
478		undefined behavior.
479
480		@par Postconditions
481		`handle()` returns a null handle. Callers needing the
482		original handle must save it, via @ref handle, before
483		calling this.
484		*/
485	2005x	void release() noexcept
486		{
487	2005x	h_ = nullptr;
488	2005x	}
489
490		/** Copy construction is disabled; a task uniquely owns its frame.
491
492		@param other The task that would be copied.
493		*/
494		task(task const& other) = delete;
495
496		/** Copy assignment is disabled; a task uniquely owns its frame.
497
498		@param other The task that would be assigned from.
499
500		@return A reference to `*this`.
501		*/
502		task& operator=(task const& other) = delete;
503
504		/** Construct by moving, transferring ownership of the frame.
505
506		@par Postconditions
507		`other` is empty and must not be awaited.
508
509		@param other The task to move from.
510		*/
511	3090x	task(task&& other) noexcept
512	3090x	: h_(std::exchange(other.h_, nullptr))
513		{
514	3090x	}
515
516		/** Assign by moving, transferring ownership of the frame.
517
518		If this task already owns a coroutine frame, that frame is
519		destroyed first. Self-assignment is a no-op.
520
521		@par Postconditions
522		`other` is empty and must not be awaited.
523
524		@param other The task to move from.
525
526		@return A reference to `*this`.
527		*/
528		task& operator=(task&& other) noexcept
529		{
530		if(this != &other)
531		{
532		if(h_)
533		h_.destroy();
534		h_ = std::exchange(other.h_, nullptr);
535		}
536		return *this;
537		}
538
539		private:
540	2772x	explicit task(std::coroutine_handle<promise_type> h)
541	2772x	: h_(h)
542		{
543	2772x	}
544		};
545
546		} // namespace capy
547		} // namespace boost
548
549		#endif
550