include/boost/corosio/detail/timeout_awaitable.hpp

100.0% Lines (61/0/61) 85.6% List of functions (125/0/146)

[ ] prev/next file

timeout_awaitable.hpp

f(x) Functions (146)

Function Calls Lines Blocks

Line	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	1935x	void operator()() const noexcept
83		{
84	1935x	src_->request_stop();
85	1935x	}
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	4x	timeout_awaitable(A&& inner, time_point deadline)
104	4x	: inner_(std::move(inner))
105	4x	, deadline_(deadline)
106		{
107	4x	}
108
109		/// Construct without a timer, deadline measured from suspension.
110	2055x	timeout_awaitable(A&& inner, std::chrono::nanoseconds dur)
111	2055x	: inner_(std::move(inner))
112	2055x	, dur_(dur)
113	2055x	, has_deadline_(false)
114		{
115	2055x	}
116
117	4120x	~timeout_awaitable()
118		{
119	4120x	destroy_parent_cb();
120	4120x	}
121
122		// Only moved before await_suspend, when cb_active_ is false
123	2061x	timeout_awaitable(timeout_awaitable&& o) noexcept(
124		std::is_nothrow_move_constructible_v<A>)
125	2061x	: inner_(std::move(o.inner_))
126	2061x	, timer_(std::move(o.timer_))
127	2061x	, deadline_(o.deadline_)
128	2061x	, dur_(o.dur_)
129	2061x	, has_deadline_(o.has_deadline_)
130	2061x	, stop_src_(std::move(o.stop_src_))
131		{
132	2061x	}
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	2057x	bool await_ready()
144		{
145	2057x	return inner_.await_ready();
146		}
147
148	2055x	auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
149		{
150	2055x	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	2055x	timer_.emplace(env->executor.context());
176		}
177	4x	catch (std::logic_error const&)
178		{
179	2x	throw_logic_error("timeout requires an io_context-backed executor");
180		}
181		auto ex =
182	2053x	static_cast<io_context&>(env->executor.context()).get_executor();
183
184	2053x	if (has_deadline_)
185	4x	timer_->expires_at(deadline_);
186		else
187	2049x	timer_->expires_after(dur_);
188
189		// Launch fire-and-forget timeout (starts suspended)
190	2053x	auto timeout = make_timeout(*timer_, stop_src_);
191	4106x	timeout.h_.promise().set_env_owned(
192	2053x	ex, stop_src_.get_token(), env->frame_allocator);
193		// Runs synchronously until timer.wait() suspends
194	2053x	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	2053x	new (cb_buf_) stop_cb_type(env->stop_token, stop_forwarder{&stop_src_});
200	2053x	cb_active_ = true;
201
202		// Start the inner op with our interposed stop_token
203	2053x	inner_env_ = {
204	2053x	env->executor, stop_src_.get_token(), env->frame_allocator};
205	4106x	return inner_.await_suspend(h, &inner_env_);
206	2053x	}
207
208	2053x	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	2053x	bool const parent = parent_token_.stop_requested();
219	2053x	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	2053x	auto r = inner_.await_resume();
225
226		// Cancel whichever is still pending (idempotent)
227	2051x	stop_src_.request_stop();
228	2051x	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	2051x	if (fired && !parent && std::get<0>(r) == capy::cond::canceled)
238		{
239	24x	std::remove_cvref_t<decltype(r)> t{};
240	24x	std::get<0>(t) = make_error_code(capy::error::timeout);
241	24x	return t;
242		}
243	2027x	return r;
244		}
245
246	6171x	void destroy_parent_cb() noexcept
247		{
248	6171x	if (cb_active_)
249		{
250	2053x	std::launder(reinterpret_cast<stop_cb_type*>(cb_buf_))
251	2053x	->~stop_cb_type();
252	2053x	cb_active_ = false;
253		}
254	6171x	}
255		};
256
257		} // namespace boost::corosio::detail
258
259		#endif
260