include/boost/corosio/detail/timeout_awaitable.hpp

100.0% Lines (60/60) 86.8% List of functions (99/114) 84.6% Branches (22/26)

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

timeout_awaitable.hpp

f(x) Functions (114)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2026 Steve Gerbino
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/corosio
8			//
9
10			#ifndef BOOST_COROSIO_DETAIL_TIMEOUT_AWAITABLE_HPP
11			#define BOOST_COROSIO_DETAIL_TIMEOUT_AWAITABLE_HPP
12
13			#include <boost/corosio/io_context.hpp>
14			#include <boost/corosio/detail/timeout_coro.hpp>
15			#include <boost/corosio/detail/timer.hpp>
16			#include <boost/corosio/detail/except.hpp>
17			#include <boost/capy/cond.hpp>
18			#include <boost/capy/error.hpp>
19			#include <boost/capy/ex/io_env.hpp>
20			#include <boost/capy/io_result.hpp>
21
22			#include <chrono>
23			#include <coroutine>
24			#include <new>
25			#include <optional>
26			#include <stdexcept>
27			#include <stop_token>
28			#include <type_traits>
29			#include <utility>
30
31			/* Races an inner IoAwaitable against a timer via a shared
32			stop_source. await_suspend arms the timer by launching a
33			fire-and-forget timeout_coro, then starts the inner op with
34			an interposed stop_token. Whichever completes first signals
35			the stop_source, cancelling the other.
36
37			Parent cancellation is forwarded through a stop_callback
38			stored in a placement-new buffer (stop_callback is not
39			movable, but the awaitable must be movable for
40			transform_awaiter). The buffer is inert during moves
41			(before await_suspend) and constructed in-place once the
42			awaitable is pinned on the coroutine frame.
43
44			The timeout_coro can outlive this awaitable — it owns its
45			env and self-destroys via suspend_never. The timer lives in
46			std::optional and is constructed lazily in await_suspend,
47			once the awaiting coroutine's executor context is known. */
48
49			namespace boost::corosio::detail {
50
51			// Local stand-in for capy::detail's io_result trait: corosio must not
52			// reach into capy::detail, but the result-mapping switch in
53			// await_resume needs to distinguish io_result from other return types.
54			template<typename T>
55			struct is_io_result : std::false_type
56			{};
57
58			template<typename... Ts>
59			struct is_io_result<capy::io_result<Ts...>> : std::true_type
60			{};
61
62			template<typename T>
63			inline constexpr bool is_io_result_v = is_io_result<T>::value;
64
65			/** Awaitable adapter that cancels an inner operation after a deadline.
66
67			Races the inner awaitable against a timer. A shared stop_source
68			ties them together: whichever completes first cancels the other.
69			Parent cancellation is forwarded via stop_callback.
70
71			The timer is constructed internally in `await_suspend` from the
72			execution context in `io_env`.
73
74			@tparam A The inner IoAwaitable type (decayed).
75			*/
76			template<typename A>
77			struct timeout_awaitable
78			{
79			struct stop_forwarder
80			{
81			std::stop_source* src_;
82		1003x	void operator()() const noexcept
83			{
84		1003x	src_->request_stop();
85		1003x	}
86			};
87
88			using time_point = std::chrono::steady_clock::time_point;
89			using stop_cb_type = std::stop_callback<stop_forwarder>;
90
91			A inner_;
92			std::optional<timer> timer_;
93			time_point deadline_;
94			std::chrono::nanoseconds dur_{};
95			bool has_deadline_ = true;
96			std::stop_source stop_src_;
97			std::stop_token parent_token_;
98			capy::io_env inner_env_;
99			alignas(stop_cb_type) unsigned char cb_buf_[sizeof(stop_cb_type)];
100			bool cb_active_ = false;
101
102			/// Construct without a timer, deadline given as an absolute time.
103		2x	timeout_awaitable(A&& inner, time_point deadline)
104		2x	: inner_(std::move(inner))
105	1/1 ✓ Branch 5 → 6 taken 2 times.	2x	, deadline_(deadline)
106			{
107		2x	}
108
109			/// Construct without a timer, deadline measured from suspension.
110		1029x	timeout_awaitable(A&& inner, std::chrono::nanoseconds dur)
111		1029x	: inner_(std::move(inner))
112		1029x	, dur_(dur)
113	2/2 ✓ Branch 5 → 6 taken 6 times. ✓ Branch 6 → 7 taken 1023 times.	1029x	, has_deadline_(false)
114			{
115		1029x	}
116
117		2063x	~timeout_awaitable()
118			{
119		2063x	destroy_parent_cb();
120		2063x	}
121
122			// Only moved before await_suspend, when cb_active_ is false
123		1032x	timeout_awaitable(timeout_awaitable&& o) noexcept(
124			std::is_nothrow_move_constructible_v<A>)
125		1032x	: inner_(std::move(o.inner_))
126		1032x	, timer_(std::move(o.timer_))
127		1032x	, deadline_(o.deadline_)
128		1032x	, dur_(o.dur_)
129		1032x	, has_deadline_(o.has_deadline_)
130		1032x	, stop_src_(std::move(o.stop_src_))
131			{
132		1032x	}
133
134			timeout_awaitable(timeout_awaitable const&) = delete;
135			timeout_awaitable& operator=(timeout_awaitable const&) = delete;
136			timeout_awaitable& operator=(timeout_awaitable&&) = delete;
137
138			// Forwarding here is load-bearing, not an optimization: awaitables
139			// may perform setup in await_ready (type-erased stream wrappers
140			// construct their cached inner op there), so the full awaiter
141			// protocol must reach inner_ before await_suspend is driven. An
142			// already-ready inner op also skips arming the timer entirely.
143		1030x	bool await_ready()
144			{
145		1030x	return inner_.await_ready();
146			}
147
148		1029x	auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
149			{
150		1029x	parent_token_ = env->stop_token;
151
152			// The deadline timer is built here from the awaiting
153			// coroutine's executor context, the first point at which it
154			// is known. await_suspend is driven through a noexcept
155			// wrapper, so a failure cannot be surfaced as a catchable
156			// exception. An executor whose context is not an io_context
157			// cannot supply a timer service; silently running the
158			// operation with no deadline would be a worse failure than
159			// aborting, so translate the service-lookup error into a
160			// clear precondition diagnostic. This terminates by design
161			// (a usage error) rather than dropping the requested timeout.
162			// The detached timeout coroutine must own its executor by
163			// value (see timeout_coro::set_env_owned); io_env carries
164			// only a non-owning executor_ref. Recover the concrete
165			// executor from the context rather than the executor_ref:
166			// wrapped executors (a strand over the io_context) satisfy
167			// the documented precondition but do not expose the io
168			// executor as their target. The timer construction below
169			// validates the context is an io_context, and the detached
170			// coroutine shares only the thread-safe stop_source with
171			// the caller, so resuming it on the raw io executor instead
172			// of the caller's wrapper is safe.
173			try
174			{
175	1/1 ✓ Branch 4 → 5 taken 1028 times.	1029x	timer_.emplace(env->executor.context());
176			}
177	1/4 ✗ Branch 29 → 30 not taken. ✓ Branch 29 → 31 taken 1 time. ✗ Branch 30 → 31 not taken. ✗ Branch 30 → 32 not taken.	2x	catch (std::logic_error const&)
178			{
179		1x	throw_logic_error("timeout requires an io_context-backed executor");
180			}
181			auto ex =
182		1028x	static_cast<io_context&>(env->executor.context()).get_executor();
183
184	2/2 ✓ Branch 7 → 8 taken 2 times. ✓ Branch 7 → 10 taken 1026 times.	1028x	if (has_deadline_)
185	1/1 ✓ Branch 9 → 12 taken 2 times.	2x	timer_->expires_at(deadline_);
186			else
187	1/1 ✓ Branch 11 → 12 taken 1026 times.	1026x	timer_->expires_after(dur_);
188
189			// Launch fire-and-forget timeout (starts suspended)
190	1/1 ✓ Branch 14 → 15 taken 1028 times.	1028x	auto timeout = make_timeout(*timer_, stop_src_);
191		2056x	timeout.h_.promise().set_env_owned(
192		2056x	ex, stop_src_.get_token(), env->frame_allocator);
193			// Runs synchronously until timer.wait() suspends
194	1/1 ✓ Branch 20 → 21 taken 1028 times.	1028x	timeout.h_.resume();
195			// timeout goes out of scope; destructor is a no-op,
196			// the coroutine self-destroys via suspend_never
197
198			// Forward parent cancellation
199		1028x	new (cb_buf_) stop_cb_type(env->stop_token, stop_forwarder{&stop_src_});
200		1028x	cb_active_ = true;
201
202			// Start the inner op with our interposed stop_token
203			inner_env_ = {
204		1028x	env->executor, stop_src_.get_token(), env->frame_allocator};
205	1/1 ✓ Branch 26 → 27 taken 1024 times.	2056x	return inner_.await_suspend(h, &inner_env_);
206		1028x	}
207
208		1028x	decltype(auto) await_resume()
209			{
210			// Read before request_stop: afterwards stop_requested()
211			// can no longer distinguish who fired first. This must also
212			// happen before inner_.await_resume() rather than after: when
213			// the inner awaitable is itself a timeout_awaitable (nested
214			// timeout()), our own request_stop() below is visible through
215			// its parent_token_ (aliasing our stop_src_), and would
216			// otherwise make its read of "parent" look like a
217			// cancellation that never happened.
218		1028x	bool const parent = parent_token_.stop_requested();
219		1028x	bool const fired = stop_src_.stop_requested();
220
221			// If inner_.await_resume() throws below, request_stop() is
222			// skipped; the still-armed timeout coroutine is then drained
223			// by timer_'s destructor rather than by us.
224	1/1 ✓ Branch 4 → 5 taken 6 times.	1028x	auto r = inner_.await_resume();
225
226			// Cancel whichever is still pending (idempotent)
227		1027x	stop_src_.request_stop();
228		1027x	destroy_parent_cb();
229
230			// Deadline won: stop_src_ is assumed to be the only
231			// cancellation source, whose only writers are the timer
232			// coroutine and the parent forwarder, so fired && !parent
233			// identifies a timeout. A third-party cancellation of the
234			// inner op (e.g. a socket cancel issued from elsewhere)
235			// landing in the same window as the deadline firing is
236			// reported as a timeout.
237	7/8 ✓ Branch 7 → 8 taken 1016 times. ✓ Branch 7 → 14 taken 11 times. ✓ Branch 8 → 9 taken 13 times. ✓ Branch 8 → 14 taken 1003 times. ✓ Branch 12 → 13 taken 13 times. ✗ Branch 12 → 14 not taken. ✓ Branch 15 → 16 taken 13 times. ✓ Branch 15 → 20 taken 1014 times.	1027x	if (fired && !parent && std::get<0>(r) == capy::cond::canceled)
238			{
239		13x	std::remove_cvref_t<decltype(r)> t{};
240		13x	std::get<0>(t) = make_error_code(capy::error::timeout);
241		13x	return t;
242			}
243		1014x	return r;
244			}
245
246		3090x	void destroy_parent_cb() noexcept
247			{
248	2/2 ✓ Branch 2 → 3 taken 1028 times. ✓ Branch 2 → 6 taken 2062 times.	3090x	if (cb_active_)
249			{
250		1028x	std::launder(reinterpret_cast<stop_cb_type*>(cb_buf_))
251		1028x	->~stop_cb_type();
252		1028x	cb_active_ = false;
253			}
254		3090x	}
255			};
256
257			} // namespace boost::corosio::detail
258
259			#endif
260