include/boost/corosio/delay.hpp

94.7% Lines (89/0/94) 74.0% List of functions (57/0/77)

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

delay.hpp

f(x) Functions (77)

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_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	16520x	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	3x	if (dur != dur)
47	3x	return nanoseconds::zero();
48		}
49	29903x	return dsec(dur) >= dsec((nanoseconds::max)())
50	29903x	? (nanoseconds::max)()
51	33031x	: dsec(dur) <= dsec((nanoseconds::min)())
52	16514x	? (nanoseconds::min)()
53	16517x	: 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	10493x	emplace_delay_timer(
61		std::optional<timer>& t, capy::execution_context& ctx)
62		{
63		try
64		{
65	10493x	t.emplace(ctx);
66		}
67	3x	catch(std::logic_error const&)
68		{
69	3x	throw_logic_error(
70		"delay requires an io_context-backed executor");
71	3x	}
72	✗	catch(std::exception const& e)
73		{
74	✗	throw_logic_error(e.what());
75	✗	}
76	10490x	}
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		std::chrono::steady_clock::time_point deadline_{};
119		std::chrono::nanoseconds dur_{};
120		bool has_deadline_ = false;
121		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	16490x	explicit delay_awaitable(std::chrono::nanoseconds dur) noexcept
128	16490x	: dur_(dur)
129		{
130	16490x	}
131
132		/// Construct an awaitable that waits until `tp`.
133	19x	explicit delay_awaitable(
134		std::chrono::steady_clock::time_point tp) noexcept
135	19x	: deadline_(tp)
136	19x	, has_deadline_(true)
137		{
138	19x	}
139
140		/// Construct by transferring state from `other`.
141		// Only moved before await_suspend; wait_ is engaged after.
142	19551x	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	16506x	bool await_ready() const noexcept
152		{
153	16506x	return false;
154		}
155
156		/// Resume inline if stopped or elapsed; else wait on a timer.
157		std::coroutine_handle<>
158	16509x	await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
159		{
160	16509x	if(env->stop_token.stop_requested())
161		{
162	6019x	canceled_ = true;
163	6019x	return h;
164		}
165
166		// Elapsed deadlines complete synchronously, but only once a
167		// pending stop request has already been ruled out above.
168	20964x	if(has_deadline_ ?
169	10490x	deadline_ <= std::chrono::steady_clock::now() :
170	10474x	dur_.count() <= 0)
171	12x	return h;
172
173	10478x	detail::emplace_delay_timer(timer_, env->executor.context());
174
175	10475x	if(has_deadline_)
176	13x	timer_->expires_at(deadline_);
177		else
178	10462x	timer_->expires_after(dur_);
179
180	10475x	wait_.emplace(timer_->wait());
181	10475x	return wait_->await_suspend(h, env);
182		}
183
184		/// Return empty on expiry, `error::canceled` if stop won.
185	16470x	[[nodiscard]] capy::io_result<> await_resume() noexcept
186		{
187	16470x	if(canceled_)
188	6019x	return {capy::error::canceled};
189	10451x	if(wait_)
190	10439x	return wait_->await_resume();
191	12x	return {};
192		}
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		bool canceled_ = false;
226		std::optional<detail::timer> timer_;
227		detail::waiter_node w_;
228
229		std::chrono::nanoseconds
230	33x	next_wait(typename Clock::time_point now) const noexcept
231		{
232	33x	return detail::clamp_to_ns(
233	66x	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	30x	static bool on_fire(void* ctx) noexcept
240		{
241	30x	auto* self = static_cast<clock_delay_awaitable*>(ctx);
242		// Canceled: resume and surface the error
243	30x	if(self->w_.ec_)
244	3x	return false;
245	27x	auto now = Clock::now();
246	27x	if(now >= self->deadline_)
247	9x	return false;
248		// Re-publish and return without touching the node again:
249		// the wait may complete on another thread immediately after.
250	18x	if(self->timer_->rearm_wait(self->w_, self->next_wait(now)))
251	18x	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		}
257
258		public:
259		/// Construct an awaitable that waits until `tp` on `Clock`.
260	1524x	explicit clock_delay_awaitable(
261		typename Clock::time_point tp) noexcept
262	1524x	: deadline_(tp)
263		{
264	1524x	}
265
266		/// Construct by transferring the deadline from `other`.
267		// Only moved before await_suspend; w_ is quiescent until then.
268	1524x	clock_delay_awaitable(clock_delay_awaitable&& other) noexcept
269	1524x	: deadline_(other.deadline_)
270		{
271	1524x	}
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	1524x	bool await_ready() const noexcept
283		{
284	1524x	return false;
285		}
286
287		/// Resume inline if stopped or reached; else wait on a timer.
288		std::coroutine_handle<>
289	1524x	await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
290		{
291	1524x	if(env->stop_token.stop_requested())
292		{
293	1506x	canceled_ = true;
294	1506x	return h;
295		}
296
297	18x	auto now = Clock::now();
298	18x	if(now >= deadline_)
299	3x	return h;
300
301	15x	detail::emplace_delay_timer(timer_, env->executor.context());
302
303	15x	timer_->expires_after(next_wait(now));
304
305	15x	w_.bind(h, *env);
306	15x	w_.on_fire_ = &on_fire;
307	15x	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	15x	return timer_->publish_wait(w_);
312		}
313
314		/// Return empty on deadline, `error::canceled` if stop won.
315	1521x	[[nodiscard]] capy::io_result<> await_resume() noexcept
316		{
317	1521x	if(canceled_)
318	1506x	return {capy::error::canceled};
319	15x	if(timer_)
320	12x	return {w_.ec_};
321	3x	return {};
322		}
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	16487x	delay(std::chrono::duration<Rep, Period> dur) noexcept
344		{
345	16487x	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	19x	delay(std::chrono::steady_clock::time_point tp) noexcept
360		{
361	19x	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	1524x	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		return clock_delay_awaitable<Clock, traits_type>(
403	1524x	std::chrono::ceil<typename Clock::duration>(tp));
404		}
405
406		} // namespace boost::corosio
407
408		#endif
409