include/boost/corosio/delay.hpp

97.2% Lines (106/109) 94.4% List of functions (67/71) 47.6% Branches (121/254)

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