include/boost/corosio/detail/timeout_awaitable.hpp

100.0% Lines (72/72) 86.3% List of functions (63/73) 48.1% Branches (100/208)

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

timeout_awaitable.hpp

f(x) Functions (73)

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