include/boost/corosio/delay.hpp

94.4% Lines (85/90) 74.6% List of functions (53/71) 82.2% Branches (37/45)

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

delay.hpp

f(x) Functions (71)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2026 Steve Gerbino
3			// Copyright (c) 2026 Michael Vandeberg
4			//
5			// Distributed under the Boost Software License, Version 1.0. (See accompanying
6			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7			//
8			// Official repository: https://github.com/cppalliance/corosio
9			//
10
11			#ifndef BOOST_COROSIO_DELAY_HPP
12			#define BOOST_COROSIO_DELAY_HPP
13
14			#include <boost/corosio/detail/config.hpp>
15			#include <boost/corosio/detail/except.hpp>
16			#include <boost/corosio/detail/timer.hpp>
17			#include <boost/corosio/wait_traits.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 <concepts>
24			#include <coroutine>
25			#include <exception>
26			#include <optional>
27			#include <stdexcept>
28			#include <system_error>
29			#include <type_traits>
30
31			namespace boost::corosio {
32
33			namespace detail {
34
35			// Narrow reps wrap if nanoseconds::max() is converted into them;
36			// a double comparison clamps safely in both directions.
37			template<typename Rep, typename Period>
38			std::chrono::nanoseconds
39		4508x	clamp_to_ns(std::chrono::duration<Rep, Period> dur) noexcept
40			{
41			using namespace std::chrono;
42			using dsec = duration<double>;
43			if constexpr (std::is_floating_point_v<Rep>)
44			{
45			// NaN fails both clamp comparisons and would reach the
46			// cast; treat it as no wait rather than undefined behavior.
47	1/2 ✓ Branch 3 → 4 taken 1 time. ✗ Branch 3 → 5 not taken.	1x	if (dur != dur)
48		1x	return nanoseconds::zero();
49			}
50	2/4 ✓ Branch 7 → 8 taken 1 time. ✓ Branch 7 → 9 taken 4506 times. ✗ Branch 9 → 10 not taken. ✗ Branch 9 → 11 not taken.	4507x	return dsec(dur) >= dsec((nanoseconds::max)()) ? (nanoseconds::max)()
51		9013x	: dsec(dur) <= dsec((nanoseconds::min)())
52	2/4 ✓ Branch 14 → 15 taken 1 time. ✓ Branch 14 → 16 taken 4505 times. ✗ Branch 15 → 16 not taken. ✗ Branch 15 → 17 not taken.	4506x	? (nanoseconds::min)()
53		4507x	: duration_cast<nanoseconds>(dur);
54			}
55
56			// A non-io_context executor cannot supply a timer service, and
57			// await_suspend is driven through a noexcept wrapper, so translate
58			// the service-lookup failure into a clear terminate.
59			inline void
60		2501x	emplace_delay_timer(std::optional<timer>& t, capy::execution_context& ctx)
61			{
62			try
63			{
64	1/1 ✓ Branch 2 → 3 taken 2500 times.	2501x	t.emplace(ctx);
65			}
66	1/3 ✗ Branch 4 → 5 not taken. ✓ Branch 4 → 6 taken 1 time. ✗ Branch 4 → 8 not taken.	1x	catch (std::logic_error const&)
67			{
68		1x	throw_logic_error("delay requires an io_context-backed executor");
69		1x	}
70		✗	catch (std::exception const& e)
71			{
72		✗	throw_logic_error(e.what());
73		✗	}
74		2500x	}
75
76			} // namespace detail
77
78			/** IoAwaitable returned by @ref delay.
79
80			Suspends the calling coroutine until the deadline elapses or
81			the environment's stop token is activated, whichever comes
82			first. A deadline already elapsed at suspension, or a stop
83			token already active, resumes the coroutine inline, without
84			starting a timer (see Cancellation below). Otherwise the
85			coroutine resumes through the executor once the timer fires
86			or a mid-wait cancellation arrives.
87
88			Not intended to be named directly; use the @ref delay factory
89			overloads instead.
90
91			@par Preconditions
92			The awaiting coroutine's executor must belong to an
93			`io_context`. Any other execution context terminates with a
94			diagnostic, because silently running without a timer would
95			drop the requested delay.
96
97			@par Cancellation
98			If stop is already requested before suspension, the coroutine
99			resumes immediately with `error::canceled`. If stop is
100			requested while suspended, the pending wait is cancelled and
101			the coroutine resumes with `error::canceled`. Requesting stop
102			from another thread while the io_context runs in
103			single_threaded mode (auto-enabled at concurrency_hint == 1)
104			is not permitted by io_context's threading rules;
105			cross-thread cancellation requires a multi-threaded-capable
106			context.
107
108			@see delay
109			*/
110			class delay_awaitable
111			{
112			// wait() names timer's private awaitable type; decltype is
113			// the only way to store it here.
114			using wait_type = decltype(std::declval<detail::timer&>().wait());
115
116			std::chrono::steady_clock::time_point deadline_{};
117			std::chrono::nanoseconds dur_{};
118			bool has_deadline_ = false;
119			bool canceled_ = false;
120			std::optional<detail::timer> timer_;
121			std::optional<wait_type> wait_;
122
123			public:
124			/// Construct an awaitable that waits for `dur` nanoseconds.
125		4498x	explicit delay_awaitable(std::chrono::nanoseconds dur) noexcept : dur_(dur)
126			{
127		4498x	}
128
129			/// Construct an awaitable that waits until `tp`.
130		13x	explicit delay_awaitable(std::chrono::steady_clock::time_point tp) noexcept
131		13x	: deadline_(tp)
132		13x	, has_deadline_(true)
133			{
134		13x	}
135
136			/// Construct by transferring state from `other`.
137			// Only moved before await_suspend; wait_ is engaged after.
138		5525x	delay_awaitable(delay_awaitable&&) = default;
139
140			delay_awaitable(delay_awaitable const&) = delete;
141			delay_awaitable& operator=(delay_awaitable const&) = delete;
142			delay_awaitable& operator=(delay_awaitable&&) = delete;
143
144			/// Return false unconditionally; see await_suspend.
145			// The elapsed-deadline fast path must run after the stop-token
146			// check, and only await_suspend receives the env carrying it.
147		4510x	bool await_ready() const noexcept
148			{
149		4510x	return false;
150			}
151
152			/// Resume inline if stopped or elapsed; else wait on a timer.
153			std::coroutine_handle<>
154		4511x	await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
155			{
156	2/2 ✓ Branch 3 → 4 taken 2011 times. ✓ Branch 3 → 5 taken 2500 times.	4511x	if (env->stop_token.stop_requested())
157			{
158		2011x	canceled_ = true;
159		2011x	return h;
160			}
161
162			// Elapsed deadlines complete synchronously, but only once a
163			// pending stop request has already been ruled out above.
164	5/5 ✓ Branch 5 → 6 taken 12 times. ✓ Branch 5 → 10 taken 2488 times. ✓ Branch 7 → 8 taken 12 times. ✓ Branch 12 → 13 taken 4 times. ✓ Branch 12 → 14 taken 2496 times.	4988x	if (has_deadline_ ? deadline_ <= std::chrono::steady_clock::now()
165		2488x	: dur_.count() <= 0)
166		4x	return h;
167
168		2496x	detail::emplace_delay_timer(timer_, env->executor.context());
169
170	2/2 ✓ Branch 16 → 17 taken 11 times. ✓ Branch 16 → 19 taken 2484 times.	2495x	if (has_deadline_)
171		11x	timer_->expires_at(deadline_);
172			else
173		2484x	timer_->expires_after(dur_);
174
175		2495x	wait_.emplace(timer_->wait());
176		2495x	return wait_->await_suspend(h, env);
177			}
178
179			/// Return empty on expiry, `error::canceled` if stop won.
180		4478x	[[nodiscard]] capy::io_result<> await_resume() noexcept
181			{
182	2/2 ✓ Branch 2 → 3 taken 2011 times. ✓ Branch 2 → 5 taken 2467 times.	4478x	if (canceled_)
183		2011x	return {capy::error::canceled};
184	2/2 ✓ Branch 6 → 7 taken 2463 times. ✓ Branch 6 → 9 taken 4 times.	2467x	if (wait_)
185		2463x	return wait_->await_resume();
186		4x	return {};
187			}
188			};
189
190			/** IoAwaitable returned by the clock overloads of @ref delay.
191
192			Suspends the calling coroutine until `Clock::now()` reaches the
193			deadline or the environment's stop token is activated. The wait
194			is a sequence of steady-clock timer waits: after each expiry the
195			clock is re-read and, if the deadline is unreached, the same
196			frame-embedded waiter is re-published for the next
197			`Traits::to_wait_duration` cap — without resuming the coroutine
198			and without allocating.
199
200			Not intended to be named directly; use the @ref delay factory
201			overloads instead.
202
203			@par Preconditions
204			The awaiting coroutine's executor must belong to an
205			`io_context`. Any other execution context terminates with a
206			diagnostic, because silently running without a timer would
207			drop the requested delay.
208
209			@par Cancellation
210			Identical to @ref delay_awaitable: stop already requested
211			resumes inline with `error::canceled`; stop while suspended
212			cancels the pending wait, including between re-arms.
213
214			@see delay, wait_traits
215			*/
216			template<class Clock, class Traits>
217			class clock_delay_awaitable
218			{
219			typename Clock::time_point deadline_{};
220			bool canceled_ = false;
221			std::optional<detail::timer> timer_;
222			detail::waiter_node w_;
223
224			std::chrono::nanoseconds
225		11x	next_wait(typename Clock::time_point now) const noexcept
226			{
227		11x	return detail::clamp_to_ns(Traits::to_wait_duration(deadline_ - now));
228			}
229
230			// Runs on the scheduler thread executing the completion op,
231			// before the continuation is posted, so the frame cannot die
232			// concurrently.
233		10x	static bool on_fire(void* ctx) noexcept
234			{
235		10x	auto* self = static_cast<clock_delay_awaitable*>(ctx);
236			// Canceled: resume and surface the error
237	2/2 ✓ Branch 3 → 4 taken 1 time. ✓ Branch 3 → 5 taken 9 times.	10x	if (self->w_.ec_)
238		1x	return false;
239		9x	auto now = Clock::now();
240	2/2 ✓ Branch 8 → 9 taken 3 times. ✓ Branch 8 → 10 taken 6 times.	9x	if (now >= self->deadline_)
241		3x	return false;
242			// Re-publish and return without touching the node again:
243			// the wait may complete on another thread immediately after.
244	1/2 ✓ Branch 13 → 14 taken 6 times. ✗ Branch 13 → 15 not taken.	6x	if (self->timer_->rearm_wait(self->w_, self->next_wait(now)))
245		6x	return true;
246			// Heap growth failed; finish the wait with an error rather
247			// than strand the frame with an unbalanced work count.
248		✗	self->w_.ec_ = std::make_error_code(std::errc::not_enough_memory);
249		✗	return false;
250			}
251
252			public:
253			/// Construct an awaitable that waits until `tp` on `Clock`.
254		508x	explicit clock_delay_awaitable(typename Clock::time_point tp) noexcept
255		508x	: deadline_(tp)
256			{
257		508x	}
258
259			/// Construct by transferring the deadline from `other`.
260			// Only moved before await_suspend; w_ is quiescent until then.
261		508x	clock_delay_awaitable(clock_delay_awaitable&& other) noexcept
262		508x	: deadline_(other.deadline_)
263			{
264		508x	}
265
266			clock_delay_awaitable(clock_delay_awaitable const&) = delete;
267			clock_delay_awaitable& operator=(clock_delay_awaitable const&) = delete;
268			clock_delay_awaitable& operator=(clock_delay_awaitable&&) = delete;
269
270			/// Return false unconditionally; see await_suspend.
271			// The elapsed-deadline fast path must run after the stop-token
272			// check, and only await_suspend receives the env carrying it.
273		508x	bool await_ready() const noexcept
274			{
275		508x	return false;
276			}
277
278			/// Resume inline if stopped or reached; else wait on a timer.
279			std::coroutine_handle<>
280		508x	await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
281			{
282	2/2 ✓ Branch 3 → 4 taken 502 times. ✓ Branch 3 → 5 taken 6 times.	508x	if (env->stop_token.stop_requested())
283			{
284		502x	canceled_ = true;
285		502x	return h;
286			}
287
288		6x	auto now = Clock::now();
289	3/3 ✓ Branch 6 → 7 taken 6 times. ✓ Branch 8 → 9 taken 1 time. ✓ Branch 8 → 10 taken 5 times.	6x	if (now >= deadline_)
290		1x	return h;
291
292	1/1 ✓ Branch 11 → 12 taken 5 times.	5x	detail::emplace_delay_timer(timer_, env->executor.context());
293
294	1/1 ✓ Branch 14 → 15 taken 5 times.	5x	timer_->expires_after(next_wait(now));
295
296		5x	w_.bind(h, *env);
297		5x	w_.on_fire_ = &on_fire;
298		5x	w_.on_fire_ctx_ = this;
299			// Never the elapsed fast path: a capped expiry that elapses
300			// before publication must still reach on_fire, not complete
301			// the clock wait early.
302	1/1 ✓ Branch 17 → 18 taken 5 times.	5x	return timer_->publish_wait(w_);
303			}
304
305			/// Return empty on deadline, `error::canceled` if stop won.
306		507x	[[nodiscard]] capy::io_result<> await_resume() noexcept
307			{
308	2/2 ✓ Branch 2 → 3 taken 502 times. ✓ Branch 2 → 5 taken 5 times.	507x	if (canceled_)
309		502x	return {capy::error::canceled};
310	2/2 ✓ Branch 6 → 7 taken 4 times. ✓ Branch 6 → 8 taken 1 time.	5x	if (timer_)
311		4x	return {w_.ec_};
312		1x	return {};
313			}
314			};
315
316			/** Suspend the current coroutine for a duration.
317
318			Returns an IoAwaitable that completes at or after the
319			specified duration, or earlier if the environment's stop
320			token is activated. Zero or negative durations complete
321			synchronously.
322
323			@par Example
324			@par !example duration
325
326			@param dur The duration to wait.
327
328			@return A @ref delay_awaitable yielding `io_result<>`.
329			*/
330			template<typename Rep, typename Period>
331			[[nodiscard]] delay_awaitable
332		4497x	delay(std::chrono::duration<Rep, Period> dur) noexcept
333			{
334		4497x	return delay_awaitable(detail::clamp_to_ns(dur));
335			}
336
337			/** Suspend the current coroutine until a time point.
338
339			Returns an IoAwaitable that completes at or after `tp`, or
340			earlier if the environment's stop token is activated. Time
341			points already reached complete synchronously.
342
343			@param tp The steady-clock time point to wait until.
344
345			@return A @ref delay_awaitable yielding `io_result<>`.
346			*/
347			[[nodiscard]] inline delay_awaitable
348		13x	delay(std::chrono::steady_clock::time_point tp) noexcept
349			{
350		13x	return delay_awaitable(tp);
351			}
352
353			/** Suspend the current coroutine until a time point on `Clock`.
354
355			Returns an IoAwaitable that completes at or after the first
356			observation of `Clock::now() >= tp`, or earlier if the
357			environment's stop token is activated. The wait is one or more
358			bounded steady-clock waits, re-reading `Clock::now()` after
359			each; `Traits::to_wait_duration` bounds each one. With the
360			default @ref wait_traits a single full-length wait is used, so
361			an adjustment of `Clock` mid-wait is observed only at natural
362			wakeup; supply capping traits to bound that latency. Time
363			points already reached complete synchronously.
364
365			@note `Clock::now()` and `Traits::to_wait_duration` are invoked
366			on the io_context's run thread and must not throw or block.
367
368			@par Example
369			@par !example system_clock_deadline
370
371			@tparam Traits The wait-traits policy; `void` selects
372			@ref wait_traits.
373
374			@param tp The time point to wait until.
375
376			@return A @ref clock_delay_awaitable yielding `io_result<>`.
377			*/
378			template<class Traits = void, class Clock, class Duration>
379			requires(!std::same_as<Clock, std::chrono::steady_clock>) &&
380			(std::is_void_v<Traits> \|\| WaitTraits<Traits, Clock>)
381			[[nodiscard]] auto
382		508x	delay(std::chrono::time_point<Clock, Duration> tp) noexcept
383			{
384			using traits_type =
385			std::conditional_t<std::is_void_v<Traits>, wait_traits<Clock>, Traits>;
386			// ceil preserves completes-at-or-after when Duration is coarser
387			// than the clock's native duration
388			return clock_delay_awaitable<Clock, traits_type>(
389		508x	std::chrono::ceil<typename Clock::duration>(tp));
390			}
391
392			} // namespace boost::corosio
393
394			#endif
395