Root/libs / corosio / include / boost / corosio / timer.hpp
Prev Index Next

libs/corosio/include/boost/corosio/timer.hpp

94.1% Lines (16/17) 100.0% Functions (10/10) 66.7% Branches (2/3)
libs/corosio/include/boost/corosio/timer.hpp
Line Branch Hits Source Code
1 //
2 // Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
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_TIMER_HPP
11 #define BOOST_COROSIO_TIMER_HPP
12
13 #include <boost/corosio/detail/config.hpp>
14 #include <boost/corosio/detail/except.hpp>
15 #include <boost/corosio/io_object.hpp>
16 #include <boost/capy/io_result.hpp>
17 #include <boost/capy/error.hpp>
18 #include <boost/capy/ex/executor_ref.hpp>
19 #include <boost/capy/ex/execution_context.hpp>
20 #include <boost/capy/concept/executor.hpp>
21 #include <system_error>
22
23 #include <chrono>
24 #include <concepts>
25 #include <coroutine>
26 #include <stop_token>
27 #include <type_traits>
28
29 namespace boost::corosio {
30
31 /** An asynchronous timer for coroutine I/O.
32
33 This class provides asynchronous timer operations that return
34 awaitable types. The timer can be used to schedule operations
35 to occur after a specified duration or at a specific time point.
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. A timer must not have concurrent wait
43 operations.
44
45 @par Semantics
46 Wraps platform timer facilities via the io_context reactor.
47 Operations dispatch to OS timer APIs (timerfd, IOCP timers,
48 kqueue EVFILT_TIMER).
49 */
50 class BOOST_COROSIO_DECL timer : public io_object
51 {
52 struct wait_awaitable
53 {
54 timer& t_;
55 std::stop_token token_;
56 mutable std::error_code ec_;
57
58 9328 explicit wait_awaitable(timer& t) noexcept : t_(t) {}
59
60 9328 bool await_ready() const noexcept
61 {
62 9328 return token_.stop_requested();
63 }
64
65 9328 capy::io_result<> await_resume() const noexcept
66 {
67
1/2
✗ Branch 1 not taken.
✓ Branch 2 taken 9328 times.
 9328 if (token_.stop_requested())
68 ✗ return {capy::error::canceled};
69 9328 return {ec_};
70 }
71
72 template<typename Ex>
73 auto await_suspend(
74 std::coroutine_handle<> h,
75 Ex const& ex) -> std::coroutine_handle<>
76 {
77 return t_.get().wait(h, ex, token_, &ec_);
78 }
79
80 template<typename Ex>
81 9328 auto await_suspend(
82 std::coroutine_handle<> h,
83 Ex const& ex,
84 std::stop_token token) -> std::coroutine_handle<>
85 {
86 9328 token_ = std::move(token);
87
1/1
✓ Branch 3 taken 9328 times.
 9328 return t_.get().wait(h, ex, token_, &ec_);
88 }
89 };
90
91 public:
92 struct timer_impl : io_object_impl
93 {
94 virtual std::coroutine_handle<> wait(
95 std::coroutine_handle<>,
96 capy::executor_ref,
97 std::stop_token,
98 std::error_code*) = 0;
99 };
100
101 public:
102 /// The clock type used for time operations.
103 using clock_type = std::chrono::steady_clock;
104
105 /// The time point type for absolute expiry times.
106 using time_point = clock_type::time_point;
107
108 /// The duration type for relative expiry times.
109 using duration = clock_type::duration;
110
111 /** Destructor.
112
113 Cancels any pending operations and releases timer resources.
114 */
115 ~timer();
116
117 /** Construct a timer from an execution context.
118
119 @param ctx The execution context that will own this timer.
120 */
121 explicit timer(capy::execution_context& ctx);
122
123 /** Move constructor.
124
125 Transfers ownership of the timer resources.
126
127 @param other The timer to move from.
128 */
129 timer(timer&& other) noexcept;
130
131 /** Move assignment operator.
132
133 Closes any existing timer and transfers ownership.
134 The source and destination must share the same execution context.
135
136 @param other The timer to move from.
137
138 @return Reference to this timer.
139
140 @throws std::logic_error if the timers have different execution contexts.
141 */
142 timer& operator=(timer&& other);
143
144 timer(timer const&) = delete;
145 timer& operator=(timer const&) = delete;
146
147 /** Cancel any pending asynchronous operations.
148
149 All outstanding operations complete with an error code that
150 compares equal to `capy::cond::canceled`.
151 */
152 void cancel();
153
154 /** Get the timer's expiry time as an absolute time.
155
156 @return The expiry time point. If no expiry has been set,
157 returns a default-constructed time_point.
158 */
159 time_point expiry() const;
160
161 /** Set the timer's expiry time as an absolute time.
162
163 Any pending asynchronous wait operations will be cancelled.
164
165 @param t The expiry time to be used for the timer.
166 */
167 void expires_at(time_point t);
168
169 /** Set the timer's expiry time relative to now.
170
171 Any pending asynchronous wait operations will be cancelled.
172
173 @param d The expiry time relative to now.
174 */
175 void expires_after(duration d);
176
177 /** Set the timer's expiry time relative to now.
178
179 This is a convenience overload that accepts any duration type
180 and converts it to the timer's native duration type.
181
182 @param d The expiry time relative to now.
183 */
184 template<class Rep, class Period>
185 9342 void expires_after(std::chrono::duration<Rep, Period> d)
186 {
187 9342 expires_after(std::chrono::duration_cast<duration>(d));
188 9342 }
189
190 /** Wait for the timer to expire.
191
192 The operation supports cancellation via `std::stop_token` through
193 the affine awaitable protocol. If the associated stop token is
194 triggered, the operation completes immediately with an error
195 that compares equal to `capy::cond::canceled`.
196
197 @par Example
198 @code
199 timer t(ctx);
200 t.expires_after(std::chrono::seconds(5));
201 auto [ec] = co_await t.wait();
202 if (ec == capy::cond::canceled)
203 {
204 // Cancelled via stop_token or cancel()
205 co_return;
206 }
207 if (ec)
208 {
209 // Handle other errors
210 co_return;
211 }
212 // Timer expired
213 @endcode
214
215 @return An awaitable that completes with `io_result<>`.
216 Returns success (default error_code) when the timer expires,
217 or an error code on failure. Compare against error conditions
218 (e.g., `ec == capy::cond::canceled`) rather than error codes.
219
220 @par Preconditions
221 The timer must have an expiry time set via expires_at() or
222 expires_after().
223 */
224 9328 auto wait()
225 {
226 9328 return wait_awaitable(*this);
227 }
228
229 private:
230 28079 timer_impl& get() const noexcept
231 {
232 28079 return *static_cast<timer_impl*>(impl_);
233 }
234 };
235
236 } // namespace boost::corosio
237
238 #endif
239