1 | // |
2 | // basic_signal_set.hpp |
3 | // ~~~~~~~~~~~~~~~~~~~~ |
4 | // |
5 | // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
6 | // |
7 | // Distributed under the Boost Software License, Version 1.0. (See accompanying |
8 | // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
9 | // |
10 | |
11 | #ifndef BOOST_ASIO_BASIC_SIGNAL_SET_HPP |
12 | #define BOOST_ASIO_BASIC_SIGNAL_SET_HPP |
13 | |
14 | #if defined(_MSC_VER) && (_MSC_VER >= 1200) |
15 | # pragma once |
16 | #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) |
17 | |
18 | #include <boost/asio/detail/config.hpp> |
19 | |
20 | #include <boost/asio/basic_io_object.hpp> |
21 | #include <boost/asio/detail/handler_type_requirements.hpp> |
22 | #include <boost/asio/detail/throw_error.hpp> |
23 | #include <boost/asio/error.hpp> |
24 | #include <boost/asio/signal_set_service.hpp> |
25 | |
26 | #include <boost/asio/detail/push_options.hpp> |
27 | |
28 | namespace boost { |
29 | namespace asio { |
30 | |
31 | /// Provides signal functionality. |
32 | /** |
33 | * The basic_signal_set class template provides the ability to perform an |
34 | * asynchronous wait for one or more signals to occur. |
35 | * |
36 | * Most applications will use the boost::asio::signal_set typedef. |
37 | * |
38 | * @par Thread Safety |
39 | * @e Distinct @e objects: Safe.@n |
40 | * @e Shared @e objects: Unsafe. |
41 | * |
42 | * @par Example |
43 | * Performing an asynchronous wait: |
44 | * @code |
45 | * void handler( |
46 | * const boost::system::error_code& error, |
47 | * int signal_number) |
48 | * { |
49 | * if (!error) |
50 | * { |
51 | * // A signal occurred. |
52 | * } |
53 | * } |
54 | * |
55 | * ... |
56 | * |
57 | * // Construct a signal set registered for process termination. |
58 | * boost::asio::signal_set signals(io_service, SIGINT, SIGTERM); |
59 | * |
60 | * // Start an asynchronous wait for one of the signals to occur. |
61 | * signals.async_wait(handler); |
62 | * @endcode |
63 | * |
64 | * @par Queueing of signal notifications |
65 | * |
66 | * If a signal is registered with a signal_set, and the signal occurs when |
67 | * there are no waiting handlers, then the signal notification is queued. The |
68 | * next async_wait operation on that signal_set will dequeue the notification. |
69 | * If multiple notifications are queued, subsequent async_wait operations |
70 | * dequeue them one at a time. Signal notifications are dequeued in order of |
71 | * ascending signal number. |
72 | * |
73 | * If a signal number is removed from a signal_set (using the @c remove or @c |
74 | * erase member functions) then any queued notifications for that signal are |
75 | * discarded. |
76 | * |
77 | * @par Multiple registration of signals |
78 | * |
79 | * The same signal number may be registered with different signal_set objects. |
80 | * When the signal occurs, one handler is called for each signal_set object. |
81 | * |
82 | * Note that multiple registration only works for signals that are registered |
83 | * using Asio. The application must not also register a signal handler using |
84 | * functions such as @c signal() or @c sigaction(). |
85 | * |
86 | * @par Signal masking on POSIX platforms |
87 | * |
88 | * POSIX allows signals to be blocked using functions such as @c sigprocmask() |
89 | * and @c pthread_sigmask(). For signals to be delivered, programs must ensure |
90 | * that any signals registered using signal_set objects are unblocked in at |
91 | * least one thread. |
92 | */ |
93 | template <typename SignalSetService = signal_set_service> |
94 | class basic_signal_set |
95 | : public basic_io_object<SignalSetService> |
96 | { |
97 | public: |
98 | /// Construct a signal set without adding any signals. |
99 | /** |
100 | * This constructor creates a signal set without registering for any signals. |
101 | * |
102 | * @param io_service The io_service object that the signal set will use to |
103 | * dispatch handlers for any asynchronous operations performed on the set. |
104 | */ |
105 | explicit basic_signal_set(boost::asio::io_service& io_service) |
106 | : basic_io_object<SignalSetService>(io_service) |
107 | { |
108 | } |
109 | |
110 | /// Construct a signal set and add one signal. |
111 | /** |
112 | * This constructor creates a signal set and registers for one signal. |
113 | * |
114 | * @param io_service The io_service object that the signal set will use to |
115 | * dispatch handlers for any asynchronous operations performed on the set. |
116 | * |
117 | * @param signal_number_1 The signal number to be added. |
118 | * |
119 | * @note This constructor is equivalent to performing: |
120 | * @code boost::asio::signal_set signals(io_service); |
121 | * signals.add(signal_number_1); @endcode |
122 | */ |
123 | basic_signal_set(boost::asio::io_service& io_service, int signal_number_1) |
124 | : basic_io_object<SignalSetService>(io_service) |
125 | { |
126 | boost::system::error_code ec; |
127 | this->service.add(this->implementation, signal_number_1, ec); |
128 | boost::asio::detail::throw_error(err: ec, location: "add" ); |
129 | } |
130 | |
131 | /// Construct a signal set and add two signals. |
132 | /** |
133 | * This constructor creates a signal set and registers for two signals. |
134 | * |
135 | * @param io_service The io_service object that the signal set will use to |
136 | * dispatch handlers for any asynchronous operations performed on the set. |
137 | * |
138 | * @param signal_number_1 The first signal number to be added. |
139 | * |
140 | * @param signal_number_2 The second signal number to be added. |
141 | * |
142 | * @note This constructor is equivalent to performing: |
143 | * @code boost::asio::signal_set signals(io_service); |
144 | * signals.add(signal_number_1); |
145 | * signals.add(signal_number_2); @endcode |
146 | */ |
147 | basic_signal_set(boost::asio::io_service& io_service, int signal_number_1, |
148 | int signal_number_2) |
149 | : basic_io_object<SignalSetService>(io_service) |
150 | { |
151 | boost::system::error_code ec; |
152 | this->service.add(this->implementation, signal_number_1, ec); |
153 | boost::asio::detail::throw_error(err: ec, location: "add" ); |
154 | this->service.add(this->implementation, signal_number_2, ec); |
155 | boost::asio::detail::throw_error(err: ec, location: "add" ); |
156 | } |
157 | |
158 | /// Construct a signal set and add three signals. |
159 | /** |
160 | * This constructor creates a signal set and registers for three signals. |
161 | * |
162 | * @param io_service The io_service object that the signal set will use to |
163 | * dispatch handlers for any asynchronous operations performed on the set. |
164 | * |
165 | * @param signal_number_1 The first signal number to be added. |
166 | * |
167 | * @param signal_number_2 The second signal number to be added. |
168 | * |
169 | * @param signal_number_3 The third signal number to be added. |
170 | * |
171 | * @note This constructor is equivalent to performing: |
172 | * @code boost::asio::signal_set signals(io_service); |
173 | * signals.add(signal_number_1); |
174 | * signals.add(signal_number_2); |
175 | * signals.add(signal_number_3); @endcode |
176 | */ |
177 | basic_signal_set(boost::asio::io_service& io_service, int signal_number_1, |
178 | int signal_number_2, int signal_number_3) |
179 | : basic_io_object<SignalSetService>(io_service) |
180 | { |
181 | boost::system::error_code ec; |
182 | this->service.add(this->implementation, signal_number_1, ec); |
183 | boost::asio::detail::throw_error(err: ec, location: "add" ); |
184 | this->service.add(this->implementation, signal_number_2, ec); |
185 | boost::asio::detail::throw_error(err: ec, location: "add" ); |
186 | this->service.add(this->implementation, signal_number_3, ec); |
187 | boost::asio::detail::throw_error(err: ec, location: "add" ); |
188 | } |
189 | |
190 | /// Add a signal to a signal_set. |
191 | /** |
192 | * This function adds the specified signal to the set. It has no effect if the |
193 | * signal is already in the set. |
194 | * |
195 | * @param signal_number The signal to be added to the set. |
196 | * |
197 | * @throws boost::system::system_error Thrown on failure. |
198 | */ |
199 | void add(int signal_number) |
200 | { |
201 | boost::system::error_code ec; |
202 | this->service.add(this->implementation, signal_number, ec); |
203 | boost::asio::detail::throw_error(err: ec, location: "add" ); |
204 | } |
205 | |
206 | /// Add a signal to a signal_set. |
207 | /** |
208 | * This function adds the specified signal to the set. It has no effect if the |
209 | * signal is already in the set. |
210 | * |
211 | * @param signal_number The signal to be added to the set. |
212 | * |
213 | * @param ec Set to indicate what error occurred, if any. |
214 | */ |
215 | boost::system::error_code add(int signal_number, |
216 | boost::system::error_code& ec) |
217 | { |
218 | return this->service.add(this->implementation, signal_number, ec); |
219 | } |
220 | |
221 | /// Remove a signal from a signal_set. |
222 | /** |
223 | * This function removes the specified signal from the set. It has no effect |
224 | * if the signal is not in the set. |
225 | * |
226 | * @param signal_number The signal to be removed from the set. |
227 | * |
228 | * @throws boost::system::system_error Thrown on failure. |
229 | * |
230 | * @note Removes any notifications that have been queued for the specified |
231 | * signal number. |
232 | */ |
233 | void remove(int signal_number) |
234 | { |
235 | boost::system::error_code ec; |
236 | this->service.remove(this->implementation, signal_number, ec); |
237 | boost::asio::detail::throw_error(err: ec, location: "remove" ); |
238 | } |
239 | |
240 | /// Remove a signal from a signal_set. |
241 | /** |
242 | * This function removes the specified signal from the set. It has no effect |
243 | * if the signal is not in the set. |
244 | * |
245 | * @param signal_number The signal to be removed from the set. |
246 | * |
247 | * @param ec Set to indicate what error occurred, if any. |
248 | * |
249 | * @note Removes any notifications that have been queued for the specified |
250 | * signal number. |
251 | */ |
252 | boost::system::error_code remove(int signal_number, |
253 | boost::system::error_code& ec) |
254 | { |
255 | return this->service.remove(this->implementation, signal_number, ec); |
256 | } |
257 | |
258 | /// Remove all signals from a signal_set. |
259 | /** |
260 | * This function removes all signals from the set. It has no effect if the set |
261 | * is already empty. |
262 | * |
263 | * @throws boost::system::system_error Thrown on failure. |
264 | * |
265 | * @note Removes all queued notifications. |
266 | */ |
267 | void clear() |
268 | { |
269 | boost::system::error_code ec; |
270 | this->service.clear(this->implementation, ec); |
271 | boost::asio::detail::throw_error(err: ec, location: "clear" ); |
272 | } |
273 | |
274 | /// Remove all signals from a signal_set. |
275 | /** |
276 | * This function removes all signals from the set. It has no effect if the set |
277 | * is already empty. |
278 | * |
279 | * @param ec Set to indicate what error occurred, if any. |
280 | * |
281 | * @note Removes all queued notifications. |
282 | */ |
283 | boost::system::error_code clear(boost::system::error_code& ec) |
284 | { |
285 | return this->service.clear(this->implementation, ec); |
286 | } |
287 | |
288 | /// Cancel all operations associated with the signal set. |
289 | /** |
290 | * This function forces the completion of any pending asynchronous wait |
291 | * operations against the signal set. The handler for each cancelled |
292 | * operation will be invoked with the boost::asio::error::operation_aborted |
293 | * error code. |
294 | * |
295 | * Cancellation does not alter the set of registered signals. |
296 | * |
297 | * @throws boost::system::system_error Thrown on failure. |
298 | * |
299 | * @note If a registered signal occurred before cancel() is called, then the |
300 | * handlers for asynchronous wait operations will: |
301 | * |
302 | * @li have already been invoked; or |
303 | * |
304 | * @li have been queued for invocation in the near future. |
305 | * |
306 | * These handlers can no longer be cancelled, and therefore are passed an |
307 | * error code that indicates the successful completion of the wait operation. |
308 | */ |
309 | void cancel() |
310 | { |
311 | boost::system::error_code ec; |
312 | this->service.cancel(this->implementation, ec); |
313 | boost::asio::detail::throw_error(err: ec, location: "cancel" ); |
314 | } |
315 | |
316 | /// Cancel all operations associated with the signal set. |
317 | /** |
318 | * This function forces the completion of any pending asynchronous wait |
319 | * operations against the signal set. The handler for each cancelled |
320 | * operation will be invoked with the boost::asio::error::operation_aborted |
321 | * error code. |
322 | * |
323 | * Cancellation does not alter the set of registered signals. |
324 | * |
325 | * @param ec Set to indicate what error occurred, if any. |
326 | * |
327 | * @note If a registered signal occurred before cancel() is called, then the |
328 | * handlers for asynchronous wait operations will: |
329 | * |
330 | * @li have already been invoked; or |
331 | * |
332 | * @li have been queued for invocation in the near future. |
333 | * |
334 | * These handlers can no longer be cancelled, and therefore are passed an |
335 | * error code that indicates the successful completion of the wait operation. |
336 | */ |
337 | boost::system::error_code cancel(boost::system::error_code& ec) |
338 | { |
339 | return this->service.cancel(this->implementation, ec); |
340 | } |
341 | |
342 | /// Start an asynchronous operation to wait for a signal to be delivered. |
343 | /** |
344 | * This function may be used to initiate an asynchronous wait against the |
345 | * signal set. It always returns immediately. |
346 | * |
347 | * For each call to async_wait(), the supplied handler will be called exactly |
348 | * once. The handler will be called when: |
349 | * |
350 | * @li One of the registered signals in the signal set occurs; or |
351 | * |
352 | * @li The signal set was cancelled, in which case the handler is passed the |
353 | * error code boost::asio::error::operation_aborted. |
354 | * |
355 | * @param handler The handler to be called when the signal occurs. Copies |
356 | * will be made of the handler as required. The function signature of the |
357 | * handler must be: |
358 | * @code void handler( |
359 | * const boost::system::error_code& error, // Result of operation. |
360 | * int signal_number // Indicates which signal occurred. |
361 | * ); @endcode |
362 | * Regardless of whether the asynchronous operation completes immediately or |
363 | * not, the handler will not be invoked from within this function. Invocation |
364 | * of the handler will be performed in a manner equivalent to using |
365 | * boost::asio::io_service::post(). |
366 | */ |
367 | template <typename SignalHandler> |
368 | BOOST_ASIO_INITFN_RESULT_TYPE(SignalHandler, |
369 | void (boost::system::error_code, int)) |
370 | async_wait(BOOST_ASIO_MOVE_ARG(SignalHandler) handler) |
371 | { |
372 | // If you get an error on the following line it means that your handler does |
373 | // not meet the documented type requirements for a SignalHandler. |
374 | BOOST_ASIO_SIGNAL_HANDLER_CHECK(SignalHandler, handler) type_check; |
375 | |
376 | return this->service.async_wait(this->implementation, |
377 | BOOST_ASIO_MOVE_CAST(SignalHandler)(handler)); |
378 | } |
379 | }; |
380 | |
381 | } // namespace asio |
382 | } // namespace boost |
383 | |
384 | #include <boost/asio/detail/pop_options.hpp> |
385 | |
386 | #endif // BOOST_ASIO_BASIC_SIGNAL_SET_HPP |
387 | |