include/boost/corosio/detail/timeout_awaitable.hpp

100.0% Lines (75 / 75) 42.5% Branches (137 / 322) 84.6% Functions (132 / 156)

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

timeout_awaitable.hpp

f(x) Functions (156)

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