]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // |
2 | // basic_signal_set.hpp | |
3 | // ~~~~~~~~~~~~~~~~~~~~ | |
4 | // | |
5 | // Copyright (c) 2003-2016 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(ec, "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(ec, "add"); | |
154 | this->service.add(this->implementation, signal_number_2, ec); | |
155 | boost::asio::detail::throw_error(ec, "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(ec, "add"); | |
184 | this->service.add(this->implementation, signal_number_2, ec); | |
185 | boost::asio::detail::throw_error(ec, "add"); | |
186 | this->service.add(this->implementation, signal_number_3, ec); | |
187 | boost::asio::detail::throw_error(ec, "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(ec, "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(ec, "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(ec, "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(ec, "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 |