Index/include / boost / corosio / signal_set.hpp

include/boost/corosio/signal_set.hpp

100.0% Lines (15/15) 100.0% Functions (8/8)
include/boost/corosio/signal_set.hpp
Prev Index Next
Line TLA Hits Source Code
1 //
2 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
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_SIGNAL_SET_HPP
12 #define BOOST_COROSIO_SIGNAL_SET_HPP
13
14 #include <boost/corosio/detail/config.hpp>
15 #include <boost/corosio/io/io_signal_set.hpp>
16 #include <boost/capy/ex/execution_context.hpp>
17 #include <boost/capy/concept/executor.hpp>
18
19 #include <concepts>
20 #include <system_error>
21
22 /*
23 Signal Set Public API
24 =====================
25
26 This header provides the public interface for asynchronous signal handling.
27 The implementation is split across platform-specific files:
28 - posix/signals.cpp: Uses sigaction() for robust signal handling
29 - iocp/signals.cpp: Uses C runtime signal() (Windows lacks sigaction)
30
31 Key design decisions:
32
33 1. Abstract flag values: The flags_t enum uses arbitrary bit positions
34 (not SA_RESTART, etc.) to avoid including <signal.h> in public headers.
35 The POSIX implementation maps these to actual SA_* constants internally.
36
37 2. Flag conflict detection: When multiple signal_sets register for the
38 same signal, they must use compatible flags. The first registration
39 establishes the flags; subsequent registrations must match or use
40 dont_care.
41
42 3. Polymorphic implementation: implementation is an abstract base that
43 platform-specific implementations (posix_signal, win_signal)
44 derive from. This allows the public API to be platform-agnostic.
45
46 4. The inline add(int) overload avoids a virtual call for the common case
47 of adding signals without flags (delegates to add(int, none)).
48 */
49
50 namespace boost::corosio {
51
52 /** An asynchronous signal set for coroutine I/O.
53
54 This class provides the ability to perform an asynchronous wait
55 for one or more signals to occur. The signal set registers for
56 signals using sigaction() on POSIX systems or the C runtime
57 signal() function on Windows.
58
59 @par Thread Safety
60 Distinct objects: Safe.@n
61 Shared objects: Unsafe. A signal_set must not have concurrent
62 wait operations.
63
64 @par Semantics
65 Wraps platform signal handling (sigaction on POSIX, C runtime
66 signal() on Windows). Operations dispatch to OS signal APIs
67 via the io_context reactor.
68
69 @par Supported Signals
70 On Windows, the following signals are supported:
71 SIGINT, SIGTERM, SIGABRT, SIGFPE, SIGILL, SIGSEGV.
72
73 @par Example
74 @code
75 signal_set signals(ctx, SIGINT, SIGTERM);
76 auto [ec, signum] = co_await signals.wait();
77 if (ec == capy::cond::canceled)
78 {
79 // Operation was cancelled via stop_token or cancel()
80 }
81 else if (!ec)
82 {
83 std::cout << "Received signal " << signum << std::endl;
84 }
85 @endcode
86 */
87 class BOOST_COROSIO_DECL signal_set : public io_signal_set
88 {
89 public:
90 /** Flags for signal registration.
91
92 These flags control the behavior of signal handling. Multiple
93 flags can be combined using the bitwise OR operator.
94
95 @note Flags only have effect on POSIX systems. On Windows,
96 only `none` and `dont_care` are supported; other flags return
97 `operation_not_supported`.
98 */
99 enum flags_t : unsigned
100 {
101 /// Use existing flags if signal is already registered.
102 /// When adding a signal that's already registered by another
103 /// signal_set, this flag indicates acceptance of whatever
104 /// flags were used for the existing registration.
105 dont_care = 1u << 16,
106
107 /// No special flags.
108 none = 0,
109
110 /// Restart interrupted system calls.
111 /// Equivalent to SA_RESTART on POSIX systems.
112 restart = 1u << 0,
113
114 /// Don't generate SIGCHLD when children stop.
115 /// Equivalent to SA_NOCLDSTOP on POSIX systems.
116 no_child_stop = 1u << 1,
117
118 /// Don't create zombie processes on child termination.
119 /// Equivalent to SA_NOCLDWAIT on POSIX systems.
120 no_child_wait = 1u << 2,
121
122 /// Don't block the signal while its handler runs.
123 /// Equivalent to SA_NODEFER on POSIX systems.
124 no_defer = 1u << 3,
125
126 /// Reset handler to SIG_DFL after one invocation.
127 /// Equivalent to SA_RESETHAND on POSIX systems.
128 reset_handler = 1u << 4
129 };
130
131 /// Combine two flag values.
132 4 friend constexpr flags_t operator|(flags_t a, flags_t b) noexcept
133 {
134 return static_cast<flags_t>(
135 4 static_cast<unsigned>(a) | static_cast<unsigned>(b));
136 }
137
138 /// Mask two flag values.
139 448 friend constexpr flags_t operator&(flags_t a, flags_t b) noexcept
140 {
141 return static_cast<flags_t>(
142 448 static_cast<unsigned>(a) & static_cast<unsigned>(b));
143 }
144
145 /// Compound assignment OR.
146 2 friend constexpr flags_t& operator|=(flags_t& a, flags_t b) noexcept
147 {
148 2 return a = a | b;
149 }
150
151 /// Compound assignment AND.
152 friend constexpr flags_t& operator&=(flags_t& a, flags_t b) noexcept
153 {
154 return a = a & b;
155 }
156
157 /// Bitwise NOT (complement).
158 friend constexpr flags_t operator~(flags_t a) noexcept
159 {
160 return static_cast<flags_t>(~static_cast<unsigned>(a));
161 }
162
163 struct implementation : io_signal_set::implementation
164 {
165 virtual std::error_code add(int signal_number, flags_t flags) = 0;
166 virtual std::error_code remove(int signal_number) = 0;
167 virtual std::error_code clear() = 0;
168 };
169
170 /** Destructor.
171
172 Cancels any pending operations and releases signal resources.
173 */
174 ~signal_set() override;
175
176 /** Construct an empty signal set.
177
178 @param ctx The execution context that will own this signal set.
179 */
180 explicit signal_set(capy::execution_context& ctx);
181
182 /** Construct a signal set with initial signals.
183
184 @param ctx The execution context that will own this signal set.
185 @param signal First signal number to add.
186 @param signals Additional signal numbers to add.
187
188 @throws std::system_error Thrown on failure.
189 */
190 template<std::convertible_to<int>... Signals>
191 36 signal_set(capy::execution_context& ctx, int signal, Signals... signals)
192 36 : signal_set(ctx)
193 {
194 auto check = [](std::error_code ec) {
195 if (ec)
196 throw std::system_error(ec);
197 };
198 36 check(add(signal));
199 6 (check(add(signals)), ...);
200 36 }
201
202 /** Move constructor.
203
204 Transfers ownership of the signal set resources.
205
206 @param other The signal set to move from.
207
208 @pre No awaitables returned by @p other's methods exist.
209 @pre The execution context associated with @p other must
210 outlive this signal set.
211 */
212 signal_set(signal_set&& other) noexcept;
213
214 /** Move assignment operator.
215
216 Closes any existing signal set and transfers ownership.
217
218 @param other The signal set to move from.
219
220 @pre No awaitables returned by either `*this` or @p other's
221 methods exist.
222 @pre The execution context associated with @p other must
223 outlive this signal set.
224
225 @return Reference to this signal set.
226 */
227 signal_set& operator=(signal_set&& other) noexcept;
228
229 signal_set(signal_set const&) = delete;
230 signal_set& operator=(signal_set const&) = delete;
231
232 /** Add a signal to the signal set.
233
234 This function adds the specified signal to the set with the
235 specified flags. It has no effect if the signal is already
236 in the set with the same flags.
237
238 If the signal is already registered globally (by another
239 signal_set) and the flags differ, an error is returned
240 unless one of them has the `dont_care` flag.
241
242 @param signal_number The signal to be added to the set.
243 @param flags The flags to apply when registering the signal.
244 On POSIX systems, these map to sigaction() flags.
245 On Windows, flags are accepted but ignored.
246
247 @return Success, or an error if the signal could not be added.
248 Returns `errc::invalid_argument` if the signal is already
249 registered with different flags.
250 */
251 std::error_code add(int signal_number, flags_t flags);
252
253 /** Add a signal to the signal set with default flags.
254
255 This is equivalent to calling `add(signal_number, none)`.
256
257 @param signal_number The signal to be added to the set.
258
259 @return Success, or an error if the signal could not be added.
260 */
261 58 std::error_code add(int signal_number)
262 {
263 58 return add(signal_number, none);
264 }
265
266 /** Remove a signal from the signal set.
267
268 This function removes the specified signal from the set. It has
269 no effect if the signal is not in the set.
270
271 @param signal_number The signal to be removed from the set.
272
273 @return Success, or an error if the signal could not be removed.
274 */
275 std::error_code remove(int signal_number);
276
277 /** Remove all signals from the signal set.
278
279 This function removes all signals from the set. It has no effect
280 if the set is already empty.
281
282 @return Success, or an error if resetting any signal handler fails.
283 */
284 std::error_code clear();
285
286 protected:
287 explicit signal_set(handle h) noexcept : io_signal_set(std::move(h)) {}
288
289 private:
290 void do_cancel() override;
291
292 116 implementation& get() const noexcept
293 {
294 116 return *static_cast<implementation*>(h_.get());
295 }
296 };
297
298 } // namespace boost::corosio
299
300 #endif
301