include/boost/corosio/timer.hpp

100.0% Lines (35/35) 100.0% List of functions (13/13) 86.7% Branches (13/15)

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

timer.hpp

f(x) Functions (13)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2025 Vinnie Falco ([email protected])
3			// Copyright (c) 2026 Steve Gerbino
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_TIMER_HPP
12			#define BOOST_COROSIO_TIMER_HPP
13
14			#include <boost/corosio/detail/config.hpp>
15			#include <boost/corosio/io/io_timer.hpp>
16			#include <boost/capy/ex/execution_context.hpp>
17			#include <boost/capy/concept/executor.hpp>
18
19			#include <chrono>
20			#include <concepts>
21			#include <cstddef>
22			#include <type_traits>
23
24			namespace boost::corosio {
25
26			/** An asynchronous timer for coroutine I/O.
27
28			This class provides asynchronous timer operations that return
29			awaitable types. The timer can be used to schedule operations
30			to occur after a specified duration or at a specific time point.
31
32			Multiple coroutines may wait concurrently on the same timer.
33			When the timer expires, all waiters complete with success. When
34			the timer is cancelled, all waiters complete with an error that
35			compares equal to `capy::cond::canceled`.
36
37			Each timer operation participates in the affine awaitable protocol,
38			ensuring coroutines resume on the correct executor.
39
40			@par Thread Safety
41			Distinct objects: Safe.@n
42			Shared objects: Unsafe.
43
44			@par Semantics
45			Timers are not backed by per-timer kernel objects. The io_context's
46			timer service keeps a process-side min-heap of pending expirations;
47			the nearest expiry drives the reactor's poll timeout, and expirations
48			are processed in the run loop.
49			*/
50			class BOOST_COROSIO_DECL timer : public io_timer
51			{
52			public:
53			/// Alias for backward compatibility.
54			using implementation = io_timer::implementation;
55
56			/** Destructor.
57
58			Cancels any pending operations and releases timer resources.
59			*/
60			~timer() override;
61
62			/** Construct a timer from an execution context.
63
64			@param ctx The execution context that will own this timer. It
65			must be a corosio io_context; otherwise the constructor
66			throws (a timer service is required).
67
68			@throws std::logic_error if @p ctx is not an io_context.
69			*/
70			explicit timer(capy::execution_context& ctx);
71
72			/** Construct a timer with an initial absolute expiry time.
73
74			@param ctx The execution context that will own this timer. It
75			must be a corosio io_context; otherwise the constructor
76			throws (a timer service is required).
77			@param t The initial expiry time point.
78
79			@throws std::logic_error if @p ctx is not an io_context.
80			*/
81			timer(capy::execution_context& ctx, time_point t);
82
83			/** Construct a timer with an initial relative expiry time.
84
85			@param ctx The execution context that will own this timer. It
86			must be a corosio io_context; otherwise the constructor
87			throws (a timer service is required).
88			@param d The initial expiry duration relative to now.
89
90			@throws std::logic_error if @p ctx is not an io_context.
91			*/
92			template<class Rep, class Period>
93		4x	timer(capy::execution_context& ctx, std::chrono::duration<Rep, Period> d)
94		4x	: timer(ctx)
95			{
96	1/1 ✓ Branch 3 → 4 taken 4 times.	4x	expires_after(d);
97		4x	}
98
99			/** Construct a timer from an executor.
100
101			The timer is associated with the executor's context, which must
102			be a corosio io_context.
103
104			@param ex The executor whose context will own this timer.
105
106			@throws std::logic_error if the executor's context is not an
107			io_context.
108			*/
109			template<class Ex>
110			requires(!std::same_as<std::remove_cvref_t<Ex>, timer>) &&
111			capy::Executor<Ex>
112		2x	explicit timer(Ex const& ex) : timer(ex.context())
113			{
114		1x	}
115
116			/** Construct a timer from an executor with an absolute expiry time.
117
118			@param ex The executor whose context will own this timer.
119			@param t The initial expiry time point.
120
121			@throws std::logic_error if the executor's context is not an
122			io_context.
123			*/
124			template<class Ex>
125			requires capy::Executor<Ex>
126		1x	timer(Ex const& ex, time_point t) : timer(ex.context(), t)
127			{
128		1x	}
129
130			/** Construct a timer from an executor with a relative expiry time.
131
132			@param ex The executor whose context will own this timer.
133			@param d The initial expiry duration relative to now.
134
135			@throws std::logic_error if the executor's context is not an
136			io_context.
137			*/
138			template<class Ex, class Rep, class Period>
139			requires capy::Executor<Ex>
140		1x	timer(Ex const& ex, std::chrono::duration<Rep, Period> d)
141		1x	: timer(ex.context(), d)
142			{
143		1x	}
144
145			/** Move constructor.
146
147			Transfers ownership of the timer resources.
148
149			@param other The timer to move from.
150
151			@pre No awaitables returned by @p other's methods exist.
152			@pre The execution context associated with @p other must
153			outlive this timer.
154			*/
155			timer(timer&& other) noexcept;
156
157			/** Move assignment operator.
158
159			Closes any existing timer and transfers ownership.
160
161			@param other The timer to move from.
162
163			@pre No awaitables returned by either `*this` or @p other's
164			methods exist.
165			@pre The execution context associated with @p other must
166			outlive this timer.
167
168			@return Reference to this timer.
169			*/
170			timer& operator=(timer&& other) noexcept;
171
172			timer(timer const&) = delete;
173			timer& operator=(timer const&) = delete;
174
175			/** Cancel one pending asynchronous wait operation.
176
177			The oldest pending wait is cancelled (FIFO order). It
178			completes with an error code that compares equal to
179			`capy::cond::canceled`.
180
181			@return The number of operations that were cancelled (0 or 1).
182			*/
183		2x	std::size_t cancel_one()
184			{
185	2/2 ✓ Branch 3 → 4 taken 1 time. ✓ Branch 3 → 5 taken 1 time.	2x	if (!get().might_have_pending_waits_)
186		1x	return 0;
187		1x	return do_cancel_one();
188			}
189
190			/** Set the timer's expiry time as an absolute time.
191
192			Any pending asynchronous wait operations will be cancelled.
193
194			@param t The expiry time to be used for the timer.
195
196			@return The number of pending operations that were cancelled.
197			*/
198		27x	std::size_t expires_at(time_point t)
199			{
200		27x	auto& impl = get();
201		27x	impl.expiry_ = t;
202	2/2 ✓ Branch 3 → 4 taken 25 times. ✓ Branch 3 → 6 taken 2 times.	27x	if (impl.heap_index_ == implementation::npos &&
203	1/2 ✓ Branch 4 → 5 taken 25 times. ✗ Branch 4 → 6 not taken.	25x	!impl.might_have_pending_waits_)
204		25x	return 0;
205		2x	return do_update_expiry();
206			}
207
208			/** Set the timer's expiry time relative to now.
209
210			Any pending asynchronous wait operations will be cancelled.
211
212			@param d The expiry time relative to now.
213
214			@return The number of pending operations that were cancelled.
215			*/
216		2294x	std::size_t expires_after(duration d)
217			{
218		2294x	auto& impl = get();
219	3/3 ✓ Branch 4 → 5 taken 2294 times. ✓ Branch 6 → 7 taken 3 times. ✓ Branch 6 → 8 taken 2291 times.	2294x	if (d <= duration::zero())
220		3x	impl.expiry_ = (time_point::min)();
221			else
222	1/1 ✓ Branch 9 → 10 taken 2291 times.	2291x	impl.expiry_ = clock_type::now() + d;
223	2/2 ✓ Branch 11 → 12 taken 2292 times. ✓ Branch 11 → 14 taken 2 times.	2294x	if (impl.heap_index_ == implementation::npos &&
224	1/2 ✓ Branch 12 → 13 taken 2292 times. ✗ Branch 12 → 14 not taken.	2292x	!impl.might_have_pending_waits_)
225		2292x	return 0;
226		2x	return do_update_expiry();
227			}
228
229			/** Set the timer's expiry time relative to now.
230
231			This is a convenience overload that accepts any duration type
232			and converts it to the timer's native duration type. Any
233			pending asynchronous wait operations will be cancelled.
234
235			@param d The expiry time relative to now.
236
237			@return The number of pending operations that were cancelled.
238			*/
239			template<class Rep, class Period>
240		2294x	std::size_t expires_after(std::chrono::duration<Rep, Period> d)
241			{
242		2294x	return expires_after(std::chrono::duration_cast<duration>(d));
243			}
244
245			protected:
246			explicit timer(handle h) noexcept : io_timer(std::move(h)) {}
247
248			private:
249			std::size_t do_cancel() override;
250			std::size_t do_cancel_one();
251			std::size_t do_update_expiry();
252
253			/// Return the underlying implementation.
254		3180x	implementation& get() const noexcept
255			{
256		3180x	return static_cast<implementation>(h_.get());
257			}
258			};
259
260			} // namespace boost::corosio
261
262			#endif
263