include/boost/capy/task.hpp

100.0% Lines (80/1/81) 95.0% List of functions (1237/2/1304)

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

task.hpp

f(x) Functions (1304)

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_TASK_HPP
11		#define BOOST_CAPY_TASK_HPP
12
13		#include <boost/capy/detail/config.hpp>
14		#include <boost/capy/concept/executor.hpp>
15		#include <boost/capy/concept/io_awaitable.hpp>
16		#include <boost/capy/ex/io_awaitable_promise_base.hpp>
17		#include <boost/capy/ex/io_env.hpp>
18		#include <boost/capy/ex/frame_allocator.hpp>
19		#include <boost/capy/detail/await_suspend_helper.hpp>
20		#include <boost/capy/io_result.hpp>
21
22		#include <exception>
23		#include <optional>
24		#include <type_traits>
25		#include <utility>
26		#include <variant>
27
28		namespace boost {
29		namespace capy {
30
31		namespace detail {
32
33		// Helper base for result storage and return_void/return_value
34		template<typename T>
35		struct task_return_base
36		{
37		std::optional<T> result_;
38
39	868x	void return_value(T value)
40		{
41	868x	result_ = std::move(value);
42	868x	}
43
44	271x	T&& result() noexcept
45		{
46	271x	return std::move(*result_);
47		}
48		};
49
50		template<>
51		struct task_return_base<void>
52		{
53	1227x	void return_void()
54		{
55	1227x	}
56		};
57
58		} // namespace detail
59
60		/** Lazy coroutine task satisfying @ref IoRunnable.
61
62		Use `task<T>` as the return type for coroutines that perform I/O
63		and return a value of type `T`. The coroutine body does not start
64		executing until the task is awaited, enabling efficient composition
65		without unnecessary eager execution.
66
67		The task participates in the I/O awaitable protocol: when awaited,
68		it receives the caller's executor and stop token, propagating them
69		to nested `co_await` expressions. This enables cancellation and
70		proper completion dispatch across executor boundaries.
71
72		@par Thread Safety
73		Distinct objects: Safe.
74		Shared objects: Unsafe.
75
76		@par Example
77
78		@code
79		task<int> compute_value()
80		{
81		auto [ec, n] = co_await stream.read_some( buf );
82		if( ec )
83		co_return 0;
84		co_return process( buf, n );
85		}
86
87		task<> run_session( tcp_socket sock )
88		{
89		int result = co_await compute_value();
90		// ...
91		}
92		@endcode
93
94		@tparam T The result type. Use `task<>` for `task<void>`.
95
96		@see IoRunnable, IoAwaitable, run, run_async
97		*/
98		template<typename T = void>
99		struct [[nodiscard]] BOOST_CAPY_CORO_AWAIT_ELIDABLE
100		task
101		{
102		/** The coroutine promise type for `task<T>`.
103
104		This is the promise object the compiler associates with a
105		`task<T>` coroutine. It satisfies the coroutine promise
106		requirements and participates in the I/O awaitable protocol via
107		@ref io_awaitable_promise_base. It is part of the coroutine
108		machinery and is not intended to be used directly by callers.
109
110		Result storage and `return_value`/`return_void` are provided by
111		`detail::task_return_base<T>`.
112
113		@see io_awaitable_promise_base, IoRunnable
114		*/
115		struct promise_type
116		: io_awaitable_promise_base<promise_type>
117		, detail::task_return_base<T>
118		{
119		private:
120		friend task;
121		union { std::exception_ptr ep_; };
122		bool has_ep_;
123
124		public:
125		/// Construct the promise with no stored exception.
126	2749x	promise_type() noexcept
127	2749x	: has_ep_(false)
128		{
129	2749x	}
130
131		/// Destroy the promise, releasing any stored exception.
132	2749x	~promise_type()
133		{
134	2749x	if(has_ep_)
135	489x	ep_.~exception_ptr();
136	2749x	}
137
138		/** Return the exception captured by the coroutine body, if any.
139
140		@return The stored exception, or a null `std::exception_ptr`
141		if the coroutine did not exit via an unhandled exception.
142		*/
143	2125x	std::exception_ptr exception() const noexcept
144		{
145	2125x	if(has_ep_)
146	730x	return ep_;
147	1395x	return {};
148		}
149
150		/** Return the owning `task` for this coroutine.
151
152		Called by the compiler to produce the object returned to the
153		caller when the coroutine is created.
154
155		@return A `task` owning the coroutine frame.
156		*/
157	2749x	task get_return_object()
158		{
159	2749x	return task{std::coroutine_handle<promise_type>::from_promise(*this)};
160		}
161
162		/** Return the initial-suspend awaiter.
163
164		The coroutine always suspends at the initial suspend point,
165		so the body does not start until the task is awaited. When the
166		body is resumed, the awaiter restores the thread-local frame
167		allocator from the stored environment.
168
169		@return An awaiter that suspends unconditionally.
170		*/
171	2749x	auto initial_suspend() noexcept
172		{
173		struct awaiter
174		{
175		promise_type* p_;
176
177	497x	bool await_ready() const noexcept
178		{
179	497x	return false;
180		}
181
182	497x	void await_suspend(std::coroutine_handle<>) const noexcept
183		{
184	497x	}
185
186	496x	void await_resume() const noexcept
187		{
188		// Restore TLS when body starts executing
189	496x	set_current_frame_allocator(p_->environment()->frame_allocator);
190	496x	}
191		};
192	2749x	return awaiter{this};
193		}
194
195		/** Return the final-suspend awaiter.
196
197		The coroutine always suspends at the final suspend point. The
198		awaiter's `await_suspend` performs symmetric transfer to the
199		stored continuation (consuming it), resuming the awaiting
200		coroutine.
201
202		@return An awaiter that suspends and transfers to the
203		continuation.
204		*/
205	2584x	auto final_suspend() noexcept
206		{
207		struct awaiter
208		{
209		promise_type* p_;
210
211	496x	bool await_ready() const noexcept
212		{
213	496x	return false;
214		}
215
216	496x	std::coroutine_handle<> await_suspend(std::coroutine_handle<>) const noexcept
217		{
218	496x	return p_->continuation();
219		}
220
221	−	void await_resume() const noexcept {} // LCOV_EXCL_LINE final_suspend awaiter, never resumed
222		};
223	2584x	return awaiter{this};
224		}
225
226		/** Capture the in-flight exception from the coroutine body.
227
228		Called by the compiler when the coroutine body exits via an
229		unhandled exception. The captured exception is rethrown when
230		the task is awaited.
231		*/
232	489x	void unhandled_exception() noexcept
233		{
234	489x	new (&ep_) std::exception_ptr(std::current_exception());
235	489x	has_ep_ = true;
236	489x	}
237
238		/** Awaiter wrapping a nested `co_await` of an @ref IoAwaitable.
239
240		Forwards the environment to the inner awaitable's
241		environment-taking `await_suspend` and restores the
242		thread-local frame allocator before the body resumes.
243
244		@tparam Awaitable The awaitable being transformed.
245		*/
246		template<class Awaitable>
247		struct transform_awaiter
248		{
249		std::decay_t<Awaitable> a_;
250		promise_type* p_;
251
252	2869x	bool await_ready() noexcept
253		{
254	2869x	return a_.await_ready();
255		}
256
257	2708x	decltype(auto) await_resume()
258		{
259		// Restore TLS before body resumes
260	2708x	set_current_frame_allocator(p_->environment()->frame_allocator);
261	2708x	return a_.await_resume();
262		}
263
264		template<class Promise>
265	2253x	auto await_suspend(std::coroutine_handle<Promise> h) noexcept
266		{
267		using R = decltype(a_.await_suspend(h, p_->environment()));
268		if constexpr (std::is_same_v<R, std::coroutine_handle<>>)
269	1253x	return detail::symmetric_transfer(a_.await_suspend(h, p_->environment()));
270		else
271	1000x	return a_.await_suspend(h, p_->environment());
272		}
273		};
274
275		/** Transform a nested awaitable before `co_await`.
276
277		Wraps an @ref IoAwaitable in a @ref transform_awaiter so the
278		coroutine's environment is propagated into it. A diagnostic
279		is emitted if the awaitable does not satisfy @ref IoAwaitable.
280
281		@param a The awaitable expression from `co_await a`.
282
283		@return A @ref transform_awaiter wrapping `a`.
284		*/
285		template<class Awaitable>
286	2869x	auto transform_awaitable(Awaitable&& a)
287		{
288		using A = std::decay_t<Awaitable>;
289		if constexpr (IoAwaitable<A>)
290		{
291		return transform_awaiter<Awaitable>{
292	4393x	std::forward<Awaitable>(a), this};
293		}
294		else
295		{
296		static_assert(sizeof(A) == 0, "requires IoAwaitable");
297		}
298	1524x	}
299		};
300
301		/** Handle to the owned coroutine frame.
302
303		Null when the task is empty (for example after a move or after
304		@ref release). Prefer @ref handle to read this; the member is
305		public for use by the coroutine machinery.
306		*/
307		std::coroutine_handle<promise_type> h_;
308
309		/// Destroy the task and its coroutine frame if owned.
310	5839x	~task()
311		{
312	5839x	if(h_)
313	767x	h_.destroy();
314	5839x	}
315
316		/** Report whether the awaited task is already complete.
317
318		Always returns `false`; a task is lazy and has not started when
319		it is awaited, so the awaiting coroutine always suspends.
320
321		@return `false`.
322		*/
323	764x	bool await_ready() const noexcept
324		{
325	764x	return false;
326		}
327
328		/** Return the task's result, rethrowing any captured exception.
329
330		If the coroutine body exited via an unhandled exception, that
331		exception is rethrown here. Otherwise the result is returned by
332		move (for `task<T>`) or nothing is returned (for `task<void>`).
333
334		@return The result value for non-void `T`; otherwise `void`.
335
336		@throws The exception captured by the coroutine body, if any.
337
338		@note Discarding an `io_result` silently drops the error
339		code, so that overload is marked `[[nodiscard]]`.
340		*/
341	552x	[[nodiscard]] auto await_resume()
342		requires detail::is_io_result_v<T>
343		{
344	552x	if(h_.promise().has_ep_)
345	105x	std::rethrow_exception(h_.promise().ep_);
346	447x	return std::move(*h_.promise().result_);
347		}
348
349	211x	auto await_resume()
350		requires (! detail::is_io_result_v<T>)
351		{
352	211x	if(h_.promise().has_ep_)
353	18x	std::rethrow_exception(h_.promise().ep_);
354		if constexpr (! std::is_void_v<T>)
355	148x	return std::move(*h_.promise().result_);
356		else
357	45x	return;
358		}
359
360		/** Start the task with the awaiting coroutine's context.
361
362		Stores `cont` as the continuation to resume on completion and
363		`env` as the execution environment propagated to nested
364		`co_await` expressions, then transfers control into the task's
365		coroutine body via the returned handle.
366
367		@param cont The awaiting coroutine to resume when the task
368		completes.
369
370		@param env The execution environment (executor, stop token, and
371		frame allocator). It must outlive the task.
372
373		@return The task's coroutine handle, for symmetric transfer.
374		*/
375	683x	std::coroutine_handle<> await_suspend(std::coroutine_handle<> cont, io_env const* env)
376		{
377	683x	h_.promise().set_continuation(cont);
378	683x	h_.promise().set_environment(env);
379	683x	return h_;
380		}
381
382		/** Return the coroutine handle.
383
384		@note Do not call `destroy()` on the returned handle while the
385		task is being awaited. The task's lifetime is normally managed
386		by `run_async`, `run`, or the awaiting parent; manually
387		destroying a suspended task that another coroutine is awaiting
388		produces undefined behavior. For cooperative cancellation, use
389		`std::stop_token`.
390
391		@return The coroutine handle.
392		*/
393	2065x	std::coroutine_handle<promise_type> handle() const noexcept
394		{
395	2065x	return h_;
396		}
397
398		/** Release ownership of the coroutine frame.
399
400		After calling this, destroying the task does not destroy the
401		coroutine frame. The caller becomes responsible for the frame's
402		lifetime.
403
404		@note If the caller intends to call `destroy()` on the
405		released handle, it must do so only when the task has not
406		started or has fully completed. Destroying a suspended task
407		that is being awaited produces undefined behavior.
408
409		@par Postconditions
410		`handle()` returns the original handle, but the task no longer
411		owns it.
412		*/
413	1982x	void release() noexcept
414		{
415	1982x	h_ = nullptr;
416	1982x	}
417
418		task(task const&) = delete;
419		task& operator=(task const&) = delete;
420
421		/** Construct by moving, transferring ownership of the frame.
422
423		@par Postconditions
424		`other` is empty and must not be awaited.
425
426		@param other The task to move from.
427		*/
428	3090x	task(task&& other) noexcept
429	3090x	: h_(std::exchange(other.h_, nullptr))
430		{
431	3090x	}
432
433		/** Assign by moving, transferring ownership of the frame.
434
435		If this task already owns a coroutine frame, that frame is
436		destroyed first. Self-assignment is a no-op.
437
438		@par Postconditions
439		`other` is empty and must not be awaited.
440
441		@param other The task to move from.
442
443		@return `*this`.
444		*/
445		task& operator=(task&& other) noexcept
446		{
447		if(this != &other)
448		{
449		if(h_)
450		h_.destroy();
451		h_ = std::exchange(other.h_, nullptr);
452		}
453		return *this;
454		}
455
456		private:
457	2749x	explicit task(std::coroutine_handle<promise_type> h)
458	2749x	: h_(h)
459		{
460	2749x	}
461		};
462
463		} // namespace capy
464		} // namespace boost
465
466		#endif
467