Index/include / boost / corosio / native / native_cancel.hpp

include/boost/corosio/native/native_cancel.hpp

100.0% Lines (4/4) 100.0% List of functions (2/2) 100.0% Branches (2/2)
[ ] prev/next file
f(x) Functions (2)
Function Calls Lines Branches Blocks
auto boost::corosio::cancel_at<boost::corosio::iocp_t{}, boost::corosio::io_timer::wait_awaitable>(boost::corosio::io_timer::wait_awaitable&&, std::chrono::time_point<std::chrono::_V2::steady_clock, std::chrono::duration<long long, std::ratio<1ll, 1000000000ll> > >) :172 3x 100.0% – 100.0% auto boost::corosio::cancel_after<boost::corosio::iocp_t{}, boost::corosio::io_timer::wait_awaitable>(boost::corosio::io_timer::wait_awaitable&&, std::chrono::duration<long long, std::ratio<1ll, 1000000000ll> >) :217 2x 100.0% 100.0% 100.0%
Line Branch TLA 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_NATIVE_NATIVE_CANCEL_HPP
11 #define BOOST_COROSIO_NATIVE_NATIVE_CANCEL_HPP
12
13 #include <boost/corosio/detail/cancel_at_awaitable.hpp>
14 #include <boost/corosio/native/native_timer.hpp>
15 #include <boost/capy/concept/io_awaitable.hpp>
16
17 #include <type_traits>
18 #include <utility>
19
20 namespace boost::corosio {
21
22 /** Cancel an operation if it does not complete by a deadline.
23
24 Overload for @ref native_timer that devirtualizes the internal
25 timer wait, allowing the compiler to inline the timer path.
26 Otherwise identical to the @ref timer overload.
27
28 If the deadline is reached first, the inner operation completes
29 with an error comparing equal to `capy::cond::canceled`. If the
30 inner operation completes first, the timer is cancelled. Parent
31 cancellation is forwarded to both.
32
33 The timer's expiry is overwritten by this call. The timer must
34 outlive the returned awaitable. Do not issue overlapping waits
35 on the same timer.
36
37 @par Completion Conditions
38 The returned awaitable resumes when either:
39 @li The inner operation completes (successfully or with error).
40 @li The deadline expires and the inner operation is cancelled.
41 @li The caller's stop token is triggered, cancelling both.
42
43 @par Error Conditions
44 @li On timeout or parent cancellation, the inner operation
45 completes with an error equal to `capy::cond::canceled`.
46 @li All other errors are propagated from the inner operation.
47
48 @par Example
49 @code
50 native_timer<epoll> t( ioc );
51 auto [ec, n] = co_await cancel_at(
52 sock.read_some( buf ), t,
53 clock::now() + 5s );
54 if (ec == capy::cond::canceled)
55 // timed out or parent cancelled
56 @endcode
57
58 @tparam Backend A backend tag value (e.g., `epoll`).
59
60 @param op The inner I/O awaitable to wrap.
61 @param t The native timer to use for the deadline. Must outlive
62 the returned awaitable.
63 @param deadline The absolute time point at which to cancel.
64
65 @return An awaitable whose result matches @p op's result type.
66
67 @see cancel_after, native_timer
68 */
69 template<auto Backend>
70 auto
71 cancel_at(
72 capy::IoAwaitable auto&& op,
73 native_timer<Backend>& t,
74 timer::time_point deadline)
75 {
76 return detail::cancel_at_awaitable<
77 std::decay_t<decltype(op)>, native_timer<Backend>>(
78 std::forward<decltype(op)>(op), t, deadline);
79 }
80
81 /** Cancel an operation if it does not complete within a duration.
82
83 Overload for @ref native_timer. Equivalent to
84 `cancel_at( op, t, clock::now() + timeout )`.
85
86 The timer's expiry is overwritten by this call. The timer must
87 outlive the returned awaitable. Do not issue overlapping waits
88 on the same timer.
89
90 @par Completion Conditions
91 The returned awaitable resumes when either:
92 @li The inner operation completes (successfully or with error).
93 @li The timeout elapses and the inner operation is cancelled.
94 @li The caller's stop token is triggered, cancelling both.
95
96 @par Error Conditions
97 @li On timeout or parent cancellation, the inner operation
98 completes with an error equal to `capy::cond::canceled`.
99 @li All other errors are propagated from the inner operation.
100
101 @par Example
102 @code
103 native_timer<epoll> t( ioc );
104 auto [ec, n] = co_await cancel_after(
105 sock.read_some( buf ), t, 5s );
106 if (ec == capy::cond::canceled)
107 // timed out
108 @endcode
109
110 @tparam Backend A backend tag value (e.g., `epoll`).
111
112 @param op The inner I/O awaitable to wrap.
113 @param t The native timer to use for the timeout. Must outlive
114 the returned awaitable.
115 @param timeout The relative duration after which to cancel.
116
117 @return An awaitable whose result matches @p op's result type.
118
119 @see cancel_at, native_timer
120 */
121 template<auto Backend>
122 auto
123 cancel_after(
124 capy::IoAwaitable auto&& op,
125 native_timer<Backend>& t,
126 timer::duration timeout)
127 {
128 return cancel_at(
129 std::forward<decltype(op)>(op), t, timer::clock_type::now() + timeout);
130 }
131
132 /** Cancel an operation if it does not complete by a deadline.
133
134 Convenience overload that creates a @ref native_timer internally,
135 devirtualizing the timer wait. Otherwise identical to the
136 explicit-timer overload.
137
138 @par Completion Conditions
139 The returned awaitable resumes when either:
140 @li The inner operation completes (successfully or with error).
141 @li The deadline expires and the inner operation is cancelled.
142 @li The caller's stop token is triggered, cancelling both.
143
144 @par Error Conditions
145 @li On timeout or parent cancellation, the inner operation
146 completes with an error equal to `capy::cond::canceled`.
147 @li All other errors are propagated from the inner operation.
148
149 @note Creates a timer per call. Use the explicit-timer overload
150 to amortize allocation across multiple timeouts.
151
152 @par Example
153 @code
154 auto [ec, n] = co_await cancel_at<epoll>(
155 sock.read_some( buf ),
156 clock::now() + 5s );
157 if (ec == capy::cond::canceled)
158 // timed out or parent cancelled
159 @endcode
160
161 @tparam Backend A backend tag value (e.g., `epoll`).
162
163 @param op The inner I/O awaitable to wrap.
164 @param deadline The absolute time point at which to cancel.
165
166 @return An awaitable whose result matches @p op's result type.
167
168 @see cancel_after, native_timer
169 */
170 template<auto Backend>
171 auto
172 3x cancel_at(capy::IoAwaitable auto&& op, timer::time_point deadline)
173 {
174 return detail::cancel_at_awaitable<
175 std::decay_t<decltype(op)>, native_timer<Backend>, true>(
176 3x std::forward<decltype(op)>(op), deadline);
177 }
178
179 /** Cancel an operation if it does not complete within a duration.
180
181 Convenience overload that creates a @ref native_timer internally.
182 Equivalent to `cancel_at<Backend>( op, clock::now() + timeout )`.
183
184 @par Completion Conditions
185 The returned awaitable resumes when either:
186 @li The inner operation completes (successfully or with error).
187 @li The timeout elapses and the inner operation is cancelled.
188 @li The caller's stop token is triggered, cancelling both.
189
190 @par Error Conditions
191 @li On timeout or parent cancellation, the inner operation
192 completes with an error equal to `capy::cond::canceled`.
193 @li All other errors are propagated from the inner operation.
194
195 @note Creates a timer per call. Use the explicit-timer overload
196 to amortize allocation across multiple timeouts.
197
198 @par Example
199 @code
200 auto [ec, n] = co_await cancel_after<epoll>(
201 sock.read_some( buf ), 5s );
202 if (ec == capy::cond::canceled)
203 // timed out
204 @endcode
205
206 @tparam Backend A backend tag value (e.g., `epoll`).
207
208 @param op The inner I/O awaitable to wrap.
209 @param timeout The relative duration after which to cancel.
210
211 @return An awaitable whose result matches @p op's result type.
212
213 @see cancel_at, native_timer
214 */
215 template<auto Backend>
216 auto
217 2x cancel_after(capy::IoAwaitable auto&& op, timer::duration timeout)
218 {
219 return cancel_at<Backend>(
220
2/2
✓ Branch 3 → 4 taken 2 times.
✓ Branch 5 → 6 taken 2 times.
 2x std::forward<decltype(op)>(op), timer::clock_type::now() + timeout);
221 }
222
223 } // namespace boost::corosio
224
225 #endif
226