Chris@16
|
1 //
|
Chris@16
|
2 // io_service.hpp
|
Chris@16
|
3 // ~~~~~~~~~~~~~~
|
Chris@16
|
4 //
|
Chris@101
|
5 // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com)
|
Chris@16
|
6 //
|
Chris@16
|
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
|
Chris@16
|
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
Chris@16
|
9 //
|
Chris@16
|
10
|
Chris@16
|
11 #ifndef BOOST_ASIO_IO_SERVICE_HPP
|
Chris@16
|
12 #define BOOST_ASIO_IO_SERVICE_HPP
|
Chris@16
|
13
|
Chris@16
|
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
|
Chris@16
|
15 # pragma once
|
Chris@16
|
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
|
Chris@16
|
17
|
Chris@16
|
18 #include <boost/asio/detail/config.hpp>
|
Chris@16
|
19 #include <cstddef>
|
Chris@16
|
20 #include <stdexcept>
|
Chris@16
|
21 #include <typeinfo>
|
Chris@16
|
22 #include <boost/asio/async_result.hpp>
|
Chris@16
|
23 #include <boost/asio/detail/noncopyable.hpp>
|
Chris@16
|
24 #include <boost/asio/detail/wrapped_handler.hpp>
|
Chris@16
|
25 #include <boost/system/error_code.hpp>
|
Chris@16
|
26
|
Chris@16
|
27 #if defined(BOOST_ASIO_WINDOWS) || defined(__CYGWIN__)
|
Chris@16
|
28 # include <boost/asio/detail/winsock_init.hpp>
|
Chris@16
|
29 #elif defined(__sun) || defined(__QNX__) || defined(__hpux) || defined(_AIX) \
|
Chris@16
|
30 || defined(__osf__)
|
Chris@16
|
31 # include <boost/asio/detail/signal_init.hpp>
|
Chris@16
|
32 #endif
|
Chris@16
|
33
|
Chris@16
|
34 #include <boost/asio/detail/push_options.hpp>
|
Chris@16
|
35
|
Chris@16
|
36 namespace boost {
|
Chris@16
|
37 namespace asio {
|
Chris@16
|
38
|
Chris@16
|
39 class io_service;
|
Chris@16
|
40 template <typename Service> Service& use_service(io_service& ios);
|
Chris@16
|
41 template <typename Service> void add_service(io_service& ios, Service* svc);
|
Chris@16
|
42 template <typename Service> bool has_service(io_service& ios);
|
Chris@16
|
43
|
Chris@16
|
44 namespace detail {
|
Chris@16
|
45 #if defined(BOOST_ASIO_HAS_IOCP)
|
Chris@16
|
46 typedef class win_iocp_io_service io_service_impl;
|
Chris@16
|
47 class win_iocp_overlapped_ptr;
|
Chris@16
|
48 #else
|
Chris@16
|
49 typedef class task_io_service io_service_impl;
|
Chris@16
|
50 #endif
|
Chris@16
|
51 class service_registry;
|
Chris@16
|
52 } // namespace detail
|
Chris@16
|
53
|
Chris@16
|
54 /// Provides core I/O functionality.
|
Chris@16
|
55 /**
|
Chris@16
|
56 * The io_service class provides the core I/O functionality for users of the
|
Chris@16
|
57 * asynchronous I/O objects, including:
|
Chris@16
|
58 *
|
Chris@16
|
59 * @li boost::asio::ip::tcp::socket
|
Chris@16
|
60 * @li boost::asio::ip::tcp::acceptor
|
Chris@16
|
61 * @li boost::asio::ip::udp::socket
|
Chris@16
|
62 * @li boost::asio::deadline_timer.
|
Chris@16
|
63 *
|
Chris@16
|
64 * The io_service class also includes facilities intended for developers of
|
Chris@16
|
65 * custom asynchronous services.
|
Chris@16
|
66 *
|
Chris@16
|
67 * @par Thread Safety
|
Chris@16
|
68 * @e Distinct @e objects: Safe.@n
|
Chris@16
|
69 * @e Shared @e objects: Safe, with the specific exceptions of the reset() and
|
Chris@16
|
70 * notify_fork() functions. Calling reset() while there are unfinished run(),
|
Chris@16
|
71 * run_one(), poll() or poll_one() calls results in undefined behaviour. The
|
Chris@16
|
72 * notify_fork() function should not be called while any io_service function,
|
Chris@16
|
73 * or any function on an I/O object that is associated with the io_service, is
|
Chris@16
|
74 * being called in another thread.
|
Chris@16
|
75 *
|
Chris@16
|
76 * @par Concepts:
|
Chris@16
|
77 * Dispatcher.
|
Chris@16
|
78 *
|
Chris@16
|
79 * @par Synchronous and asynchronous operations
|
Chris@16
|
80 *
|
Chris@16
|
81 * Synchronous operations on I/O objects implicitly run the io_service object
|
Chris@16
|
82 * for an individual operation. The io_service functions run(), run_one(),
|
Chris@16
|
83 * poll() or poll_one() must be called for the io_service to perform
|
Chris@16
|
84 * asynchronous operations on behalf of a C++ program. Notification that an
|
Chris@16
|
85 * asynchronous operation has completed is delivered by invocation of the
|
Chris@16
|
86 * associated handler. Handlers are invoked only by a thread that is currently
|
Chris@16
|
87 * calling any overload of run(), run_one(), poll() or poll_one() for the
|
Chris@16
|
88 * io_service.
|
Chris@16
|
89 *
|
Chris@16
|
90 * @par Effect of exceptions thrown from handlers
|
Chris@16
|
91 *
|
Chris@16
|
92 * If an exception is thrown from a handler, the exception is allowed to
|
Chris@16
|
93 * propagate through the throwing thread's invocation of run(), run_one(),
|
Chris@16
|
94 * poll() or poll_one(). No other threads that are calling any of these
|
Chris@16
|
95 * functions are affected. It is then the responsibility of the application to
|
Chris@16
|
96 * catch the exception.
|
Chris@16
|
97 *
|
Chris@16
|
98 * After the exception has been caught, the run(), run_one(), poll() or
|
Chris@16
|
99 * poll_one() call may be restarted @em without the need for an intervening
|
Chris@16
|
100 * call to reset(). This allows the thread to rejoin the io_service object's
|
Chris@16
|
101 * thread pool without impacting any other threads in the pool.
|
Chris@16
|
102 *
|
Chris@16
|
103 * For example:
|
Chris@16
|
104 *
|
Chris@16
|
105 * @code
|
Chris@16
|
106 * boost::asio::io_service io_service;
|
Chris@16
|
107 * ...
|
Chris@16
|
108 * for (;;)
|
Chris@16
|
109 * {
|
Chris@16
|
110 * try
|
Chris@16
|
111 * {
|
Chris@16
|
112 * io_service.run();
|
Chris@16
|
113 * break; // run() exited normally
|
Chris@16
|
114 * }
|
Chris@16
|
115 * catch (my_exception& e)
|
Chris@16
|
116 * {
|
Chris@16
|
117 * // Deal with exception as appropriate.
|
Chris@16
|
118 * }
|
Chris@16
|
119 * }
|
Chris@16
|
120 * @endcode
|
Chris@16
|
121 *
|
Chris@16
|
122 * @par Stopping the io_service from running out of work
|
Chris@16
|
123 *
|
Chris@16
|
124 * Some applications may need to prevent an io_service object's run() call from
|
Chris@16
|
125 * returning when there is no more work to do. For example, the io_service may
|
Chris@16
|
126 * be being run in a background thread that is launched prior to the
|
Chris@16
|
127 * application's asynchronous operations. The run() call may be kept running by
|
Chris@16
|
128 * creating an object of type boost::asio::io_service::work:
|
Chris@16
|
129 *
|
Chris@16
|
130 * @code boost::asio::io_service io_service;
|
Chris@16
|
131 * boost::asio::io_service::work work(io_service);
|
Chris@16
|
132 * ... @endcode
|
Chris@16
|
133 *
|
Chris@16
|
134 * To effect a shutdown, the application will then need to call the io_service
|
Chris@16
|
135 * object's stop() member function. This will cause the io_service run() call
|
Chris@16
|
136 * to return as soon as possible, abandoning unfinished operations and without
|
Chris@16
|
137 * permitting ready handlers to be dispatched.
|
Chris@16
|
138 *
|
Chris@16
|
139 * Alternatively, if the application requires that all operations and handlers
|
Chris@16
|
140 * be allowed to finish normally, the work object may be explicitly destroyed.
|
Chris@16
|
141 *
|
Chris@16
|
142 * @code boost::asio::io_service io_service;
|
Chris@16
|
143 * auto_ptr<boost::asio::io_service::work> work(
|
Chris@16
|
144 * new boost::asio::io_service::work(io_service));
|
Chris@16
|
145 * ...
|
Chris@16
|
146 * work.reset(); // Allow run() to exit. @endcode
|
Chris@16
|
147 *
|
Chris@16
|
148 * @par The io_service class and I/O services
|
Chris@16
|
149 *
|
Chris@16
|
150 * Class io_service implements an extensible, type-safe, polymorphic set of I/O
|
Chris@16
|
151 * services, indexed by service type. An object of class io_service must be
|
Chris@16
|
152 * initialised before I/O objects such as sockets, resolvers and timers can be
|
Chris@16
|
153 * used. These I/O objects are distinguished by having constructors that accept
|
Chris@16
|
154 * an @c io_service& parameter.
|
Chris@16
|
155 *
|
Chris@16
|
156 * I/O services exist to manage the logical interface to the operating system on
|
Chris@16
|
157 * behalf of the I/O objects. In particular, there are resources that are shared
|
Chris@16
|
158 * across a class of I/O objects. For example, timers may be implemented in
|
Chris@16
|
159 * terms of a single timer queue. The I/O services manage these shared
|
Chris@16
|
160 * resources.
|
Chris@16
|
161 *
|
Chris@16
|
162 * Access to the services of an io_service is via three function templates,
|
Chris@16
|
163 * use_service(), add_service() and has_service().
|
Chris@16
|
164 *
|
Chris@16
|
165 * In a call to @c use_service<Service>(), the type argument chooses a service,
|
Chris@16
|
166 * making available all members of the named type. If @c Service is not present
|
Chris@16
|
167 * in an io_service, an object of type @c Service is created and added to the
|
Chris@16
|
168 * io_service. A C++ program can check if an io_service implements a
|
Chris@16
|
169 * particular service with the function template @c has_service<Service>().
|
Chris@16
|
170 *
|
Chris@16
|
171 * Service objects may be explicitly added to an io_service using the function
|
Chris@16
|
172 * template @c add_service<Service>(). If the @c Service is already present, the
|
Chris@16
|
173 * service_already_exists exception is thrown. If the owner of the service is
|
Chris@16
|
174 * not the same object as the io_service parameter, the invalid_service_owner
|
Chris@16
|
175 * exception is thrown.
|
Chris@16
|
176 *
|
Chris@16
|
177 * Once a service reference is obtained from an io_service object by calling
|
Chris@16
|
178 * use_service(), that reference remains usable as long as the owning io_service
|
Chris@16
|
179 * object exists.
|
Chris@16
|
180 *
|
Chris@16
|
181 * All I/O service implementations have io_service::service as a public base
|
Chris@16
|
182 * class. Custom I/O services may be implemented by deriving from this class and
|
Chris@16
|
183 * then added to an io_service using the facilities described above.
|
Chris@16
|
184 */
|
Chris@16
|
185 class io_service
|
Chris@16
|
186 : private noncopyable
|
Chris@16
|
187 {
|
Chris@16
|
188 private:
|
Chris@16
|
189 typedef detail::io_service_impl impl_type;
|
Chris@16
|
190 #if defined(BOOST_ASIO_HAS_IOCP)
|
Chris@16
|
191 friend class detail::win_iocp_overlapped_ptr;
|
Chris@16
|
192 #endif
|
Chris@16
|
193
|
Chris@16
|
194 public:
|
Chris@16
|
195 class work;
|
Chris@16
|
196 friend class work;
|
Chris@16
|
197
|
Chris@16
|
198 class id;
|
Chris@16
|
199
|
Chris@16
|
200 class service;
|
Chris@16
|
201
|
Chris@16
|
202 class strand;
|
Chris@16
|
203
|
Chris@16
|
204 /// Constructor.
|
Chris@16
|
205 BOOST_ASIO_DECL io_service();
|
Chris@16
|
206
|
Chris@16
|
207 /// Constructor.
|
Chris@16
|
208 /**
|
Chris@16
|
209 * Construct with a hint about the required level of concurrency.
|
Chris@16
|
210 *
|
Chris@16
|
211 * @param concurrency_hint A suggestion to the implementation on how many
|
Chris@16
|
212 * threads it should allow to run simultaneously.
|
Chris@16
|
213 */
|
Chris@16
|
214 BOOST_ASIO_DECL explicit io_service(std::size_t concurrency_hint);
|
Chris@16
|
215
|
Chris@16
|
216 /// Destructor.
|
Chris@16
|
217 /**
|
Chris@16
|
218 * On destruction, the io_service performs the following sequence of
|
Chris@16
|
219 * operations:
|
Chris@16
|
220 *
|
Chris@16
|
221 * @li For each service object @c svc in the io_service set, in reverse order
|
Chris@16
|
222 * of the beginning of service object lifetime, performs
|
Chris@16
|
223 * @c svc->shutdown_service().
|
Chris@16
|
224 *
|
Chris@16
|
225 * @li Uninvoked handler objects that were scheduled for deferred invocation
|
Chris@16
|
226 * on the io_service, or any associated strand, are destroyed.
|
Chris@16
|
227 *
|
Chris@16
|
228 * @li For each service object @c svc in the io_service set, in reverse order
|
Chris@16
|
229 * of the beginning of service object lifetime, performs
|
Chris@16
|
230 * <tt>delete static_cast<io_service::service*>(svc)</tt>.
|
Chris@16
|
231 *
|
Chris@16
|
232 * @note The destruction sequence described above permits programs to
|
Chris@16
|
233 * simplify their resource management by using @c shared_ptr<>. Where an
|
Chris@16
|
234 * object's lifetime is tied to the lifetime of a connection (or some other
|
Chris@16
|
235 * sequence of asynchronous operations), a @c shared_ptr to the object would
|
Chris@16
|
236 * be bound into the handlers for all asynchronous operations associated with
|
Chris@16
|
237 * it. This works as follows:
|
Chris@16
|
238 *
|
Chris@16
|
239 * @li When a single connection ends, all associated asynchronous operations
|
Chris@16
|
240 * complete. The corresponding handler objects are destroyed, and all
|
Chris@16
|
241 * @c shared_ptr references to the objects are destroyed.
|
Chris@16
|
242 *
|
Chris@16
|
243 * @li To shut down the whole program, the io_service function stop() is
|
Chris@16
|
244 * called to terminate any run() calls as soon as possible. The io_service
|
Chris@16
|
245 * destructor defined above destroys all handlers, causing all @c shared_ptr
|
Chris@16
|
246 * references to all connection objects to be destroyed.
|
Chris@16
|
247 */
|
Chris@16
|
248 BOOST_ASIO_DECL ~io_service();
|
Chris@16
|
249
|
Chris@16
|
250 /// Run the io_service object's event processing loop.
|
Chris@16
|
251 /**
|
Chris@16
|
252 * The run() function blocks until all work has finished and there are no
|
Chris@16
|
253 * more handlers to be dispatched, or until the io_service has been stopped.
|
Chris@16
|
254 *
|
Chris@16
|
255 * Multiple threads may call the run() function to set up a pool of threads
|
Chris@16
|
256 * from which the io_service may execute handlers. All threads that are
|
Chris@16
|
257 * waiting in the pool are equivalent and the io_service may choose any one
|
Chris@16
|
258 * of them to invoke a handler.
|
Chris@16
|
259 *
|
Chris@16
|
260 * A normal exit from the run() function implies that the io_service object
|
Chris@16
|
261 * is stopped (the stopped() function returns @c true). Subsequent calls to
|
Chris@16
|
262 * run(), run_one(), poll() or poll_one() will return immediately unless there
|
Chris@16
|
263 * is a prior call to reset().
|
Chris@16
|
264 *
|
Chris@16
|
265 * @return The number of handlers that were executed.
|
Chris@16
|
266 *
|
Chris@16
|
267 * @throws boost::system::system_error Thrown on failure.
|
Chris@16
|
268 *
|
Chris@16
|
269 * @note The run() function must not be called from a thread that is currently
|
Chris@16
|
270 * calling one of run(), run_one(), poll() or poll_one() on the same
|
Chris@16
|
271 * io_service object.
|
Chris@16
|
272 *
|
Chris@16
|
273 * The poll() function may also be used to dispatch ready handlers, but
|
Chris@16
|
274 * without blocking.
|
Chris@16
|
275 */
|
Chris@16
|
276 BOOST_ASIO_DECL std::size_t run();
|
Chris@16
|
277
|
Chris@16
|
278 /// Run the io_service object's event processing loop.
|
Chris@16
|
279 /**
|
Chris@16
|
280 * The run() function blocks until all work has finished and there are no
|
Chris@16
|
281 * more handlers to be dispatched, or until the io_service has been stopped.
|
Chris@16
|
282 *
|
Chris@16
|
283 * Multiple threads may call the run() function to set up a pool of threads
|
Chris@16
|
284 * from which the io_service may execute handlers. All threads that are
|
Chris@16
|
285 * waiting in the pool are equivalent and the io_service may choose any one
|
Chris@16
|
286 * of them to invoke a handler.
|
Chris@16
|
287 *
|
Chris@16
|
288 * A normal exit from the run() function implies that the io_service object
|
Chris@16
|
289 * is stopped (the stopped() function returns @c true). Subsequent calls to
|
Chris@16
|
290 * run(), run_one(), poll() or poll_one() will return immediately unless there
|
Chris@16
|
291 * is a prior call to reset().
|
Chris@16
|
292 *
|
Chris@16
|
293 * @param ec Set to indicate what error occurred, if any.
|
Chris@16
|
294 *
|
Chris@16
|
295 * @return The number of handlers that were executed.
|
Chris@16
|
296 *
|
Chris@16
|
297 * @note The run() function must not be called from a thread that is currently
|
Chris@16
|
298 * calling one of run(), run_one(), poll() or poll_one() on the same
|
Chris@16
|
299 * io_service object.
|
Chris@16
|
300 *
|
Chris@16
|
301 * The poll() function may also be used to dispatch ready handlers, but
|
Chris@16
|
302 * without blocking.
|
Chris@16
|
303 */
|
Chris@16
|
304 BOOST_ASIO_DECL std::size_t run(boost::system::error_code& ec);
|
Chris@16
|
305
|
Chris@16
|
306 /// Run the io_service object's event processing loop to execute at most one
|
Chris@16
|
307 /// handler.
|
Chris@16
|
308 /**
|
Chris@16
|
309 * The run_one() function blocks until one handler has been dispatched, or
|
Chris@16
|
310 * until the io_service has been stopped.
|
Chris@16
|
311 *
|
Chris@16
|
312 * @return The number of handlers that were executed. A zero return value
|
Chris@16
|
313 * implies that the io_service object is stopped (the stopped() function
|
Chris@16
|
314 * returns @c true). Subsequent calls to run(), run_one(), poll() or
|
Chris@16
|
315 * poll_one() will return immediately unless there is a prior call to
|
Chris@16
|
316 * reset().
|
Chris@16
|
317 *
|
Chris@16
|
318 * @throws boost::system::system_error Thrown on failure.
|
Chris@16
|
319 */
|
Chris@16
|
320 BOOST_ASIO_DECL std::size_t run_one();
|
Chris@16
|
321
|
Chris@16
|
322 /// Run the io_service object's event processing loop to execute at most one
|
Chris@16
|
323 /// handler.
|
Chris@16
|
324 /**
|
Chris@16
|
325 * The run_one() function blocks until one handler has been dispatched, or
|
Chris@16
|
326 * until the io_service has been stopped.
|
Chris@16
|
327 *
|
Chris@16
|
328 * @return The number of handlers that were executed. A zero return value
|
Chris@16
|
329 * implies that the io_service object is stopped (the stopped() function
|
Chris@16
|
330 * returns @c true). Subsequent calls to run(), run_one(), poll() or
|
Chris@16
|
331 * poll_one() will return immediately unless there is a prior call to
|
Chris@16
|
332 * reset().
|
Chris@16
|
333 *
|
Chris@16
|
334 * @return The number of handlers that were executed.
|
Chris@16
|
335 */
|
Chris@16
|
336 BOOST_ASIO_DECL std::size_t run_one(boost::system::error_code& ec);
|
Chris@16
|
337
|
Chris@16
|
338 /// Run the io_service object's event processing loop to execute ready
|
Chris@16
|
339 /// handlers.
|
Chris@16
|
340 /**
|
Chris@16
|
341 * The poll() function runs handlers that are ready to run, without blocking,
|
Chris@16
|
342 * until the io_service has been stopped or there are no more ready handlers.
|
Chris@16
|
343 *
|
Chris@16
|
344 * @return The number of handlers that were executed.
|
Chris@16
|
345 *
|
Chris@16
|
346 * @throws boost::system::system_error Thrown on failure.
|
Chris@16
|
347 */
|
Chris@16
|
348 BOOST_ASIO_DECL std::size_t poll();
|
Chris@16
|
349
|
Chris@16
|
350 /// Run the io_service object's event processing loop to execute ready
|
Chris@16
|
351 /// handlers.
|
Chris@16
|
352 /**
|
Chris@16
|
353 * The poll() function runs handlers that are ready to run, without blocking,
|
Chris@16
|
354 * until the io_service has been stopped or there are no more ready handlers.
|
Chris@16
|
355 *
|
Chris@16
|
356 * @param ec Set to indicate what error occurred, if any.
|
Chris@16
|
357 *
|
Chris@16
|
358 * @return The number of handlers that were executed.
|
Chris@16
|
359 */
|
Chris@16
|
360 BOOST_ASIO_DECL std::size_t poll(boost::system::error_code& ec);
|
Chris@16
|
361
|
Chris@16
|
362 /// Run the io_service object's event processing loop to execute one ready
|
Chris@16
|
363 /// handler.
|
Chris@16
|
364 /**
|
Chris@16
|
365 * The poll_one() function runs at most one handler that is ready to run,
|
Chris@16
|
366 * without blocking.
|
Chris@16
|
367 *
|
Chris@16
|
368 * @return The number of handlers that were executed.
|
Chris@16
|
369 *
|
Chris@16
|
370 * @throws boost::system::system_error Thrown on failure.
|
Chris@16
|
371 */
|
Chris@16
|
372 BOOST_ASIO_DECL std::size_t poll_one();
|
Chris@16
|
373
|
Chris@16
|
374 /// Run the io_service object's event processing loop to execute one ready
|
Chris@16
|
375 /// handler.
|
Chris@16
|
376 /**
|
Chris@16
|
377 * The poll_one() function runs at most one handler that is ready to run,
|
Chris@16
|
378 * without blocking.
|
Chris@16
|
379 *
|
Chris@16
|
380 * @param ec Set to indicate what error occurred, if any.
|
Chris@16
|
381 *
|
Chris@16
|
382 * @return The number of handlers that were executed.
|
Chris@16
|
383 */
|
Chris@16
|
384 BOOST_ASIO_DECL std::size_t poll_one(boost::system::error_code& ec);
|
Chris@16
|
385
|
Chris@16
|
386 /// Stop the io_service object's event processing loop.
|
Chris@16
|
387 /**
|
Chris@16
|
388 * This function does not block, but instead simply signals the io_service to
|
Chris@16
|
389 * stop. All invocations of its run() or run_one() member functions should
|
Chris@16
|
390 * return as soon as possible. Subsequent calls to run(), run_one(), poll()
|
Chris@16
|
391 * or poll_one() will return immediately until reset() is called.
|
Chris@16
|
392 */
|
Chris@16
|
393 BOOST_ASIO_DECL void stop();
|
Chris@16
|
394
|
Chris@16
|
395 /// Determine whether the io_service object has been stopped.
|
Chris@16
|
396 /**
|
Chris@16
|
397 * This function is used to determine whether an io_service object has been
|
Chris@16
|
398 * stopped, either through an explicit call to stop(), or due to running out
|
Chris@16
|
399 * of work. When an io_service object is stopped, calls to run(), run_one(),
|
Chris@16
|
400 * poll() or poll_one() will return immediately without invoking any
|
Chris@16
|
401 * handlers.
|
Chris@16
|
402 *
|
Chris@16
|
403 * @return @c true if the io_service object is stopped, otherwise @c false.
|
Chris@16
|
404 */
|
Chris@16
|
405 BOOST_ASIO_DECL bool stopped() const;
|
Chris@16
|
406
|
Chris@16
|
407 /// Reset the io_service in preparation for a subsequent run() invocation.
|
Chris@16
|
408 /**
|
Chris@16
|
409 * This function must be called prior to any second or later set of
|
Chris@16
|
410 * invocations of the run(), run_one(), poll() or poll_one() functions when a
|
Chris@16
|
411 * previous invocation of these functions returned due to the io_service
|
Chris@16
|
412 * being stopped or running out of work. After a call to reset(), the
|
Chris@16
|
413 * io_service object's stopped() function will return @c false.
|
Chris@16
|
414 *
|
Chris@16
|
415 * This function must not be called while there are any unfinished calls to
|
Chris@16
|
416 * the run(), run_one(), poll() or poll_one() functions.
|
Chris@16
|
417 */
|
Chris@16
|
418 BOOST_ASIO_DECL void reset();
|
Chris@16
|
419
|
Chris@16
|
420 /// Request the io_service to invoke the given handler.
|
Chris@16
|
421 /**
|
Chris@16
|
422 * This function is used to ask the io_service to execute the given handler.
|
Chris@16
|
423 *
|
Chris@16
|
424 * The io_service guarantees that the handler will only be called in a thread
|
Chris@16
|
425 * in which the run(), run_one(), poll() or poll_one() member functions is
|
Chris@16
|
426 * currently being invoked. The handler may be executed inside this function
|
Chris@16
|
427 * if the guarantee can be met.
|
Chris@16
|
428 *
|
Chris@16
|
429 * @param handler The handler to be called. The io_service will make
|
Chris@16
|
430 * a copy of the handler object as required. The function signature of the
|
Chris@16
|
431 * handler must be: @code void handler(); @endcode
|
Chris@16
|
432 *
|
Chris@16
|
433 * @note This function throws an exception only if:
|
Chris@16
|
434 *
|
Chris@16
|
435 * @li the handler's @c asio_handler_allocate function; or
|
Chris@16
|
436 *
|
Chris@16
|
437 * @li the handler's copy constructor
|
Chris@16
|
438 *
|
Chris@16
|
439 * throws an exception.
|
Chris@16
|
440 */
|
Chris@16
|
441 template <typename CompletionHandler>
|
Chris@16
|
442 BOOST_ASIO_INITFN_RESULT_TYPE(CompletionHandler, void ())
|
Chris@16
|
443 dispatch(BOOST_ASIO_MOVE_ARG(CompletionHandler) handler);
|
Chris@16
|
444
|
Chris@16
|
445 /// Request the io_service to invoke the given handler and return immediately.
|
Chris@16
|
446 /**
|
Chris@16
|
447 * This function is used to ask the io_service to execute the given handler,
|
Chris@16
|
448 * but without allowing the io_service to call the handler from inside this
|
Chris@16
|
449 * function.
|
Chris@16
|
450 *
|
Chris@16
|
451 * The io_service guarantees that the handler will only be called in a thread
|
Chris@16
|
452 * in which the run(), run_one(), poll() or poll_one() member functions is
|
Chris@16
|
453 * currently being invoked.
|
Chris@16
|
454 *
|
Chris@16
|
455 * @param handler The handler to be called. The io_service will make
|
Chris@16
|
456 * a copy of the handler object as required. The function signature of the
|
Chris@16
|
457 * handler must be: @code void handler(); @endcode
|
Chris@16
|
458 *
|
Chris@16
|
459 * @note This function throws an exception only if:
|
Chris@16
|
460 *
|
Chris@16
|
461 * @li the handler's @c asio_handler_allocate function; or
|
Chris@16
|
462 *
|
Chris@16
|
463 * @li the handler's copy constructor
|
Chris@16
|
464 *
|
Chris@16
|
465 * throws an exception.
|
Chris@16
|
466 */
|
Chris@16
|
467 template <typename CompletionHandler>
|
Chris@16
|
468 BOOST_ASIO_INITFN_RESULT_TYPE(CompletionHandler, void ())
|
Chris@16
|
469 post(BOOST_ASIO_MOVE_ARG(CompletionHandler) handler);
|
Chris@16
|
470
|
Chris@16
|
471 /// Create a new handler that automatically dispatches the wrapped handler
|
Chris@16
|
472 /// on the io_service.
|
Chris@16
|
473 /**
|
Chris@16
|
474 * This function is used to create a new handler function object that, when
|
Chris@16
|
475 * invoked, will automatically pass the wrapped handler to the io_service
|
Chris@16
|
476 * object's dispatch function.
|
Chris@16
|
477 *
|
Chris@16
|
478 * @param handler The handler to be wrapped. The io_service will make a copy
|
Chris@16
|
479 * of the handler object as required. The function signature of the handler
|
Chris@16
|
480 * must be: @code void handler(A1 a1, ... An an); @endcode
|
Chris@16
|
481 *
|
Chris@16
|
482 * @return A function object that, when invoked, passes the wrapped handler to
|
Chris@16
|
483 * the io_service object's dispatch function. Given a function object with the
|
Chris@16
|
484 * signature:
|
Chris@16
|
485 * @code R f(A1 a1, ... An an); @endcode
|
Chris@16
|
486 * If this function object is passed to the wrap function like so:
|
Chris@16
|
487 * @code io_service.wrap(f); @endcode
|
Chris@16
|
488 * then the return value is a function object with the signature
|
Chris@16
|
489 * @code void g(A1 a1, ... An an); @endcode
|
Chris@16
|
490 * that, when invoked, executes code equivalent to:
|
Chris@16
|
491 * @code io_service.dispatch(boost::bind(f, a1, ... an)); @endcode
|
Chris@16
|
492 */
|
Chris@16
|
493 template <typename Handler>
|
Chris@16
|
494 #if defined(GENERATING_DOCUMENTATION)
|
Chris@16
|
495 unspecified
|
Chris@16
|
496 #else
|
Chris@16
|
497 detail::wrapped_handler<io_service&, Handler>
|
Chris@16
|
498 #endif
|
Chris@16
|
499 wrap(Handler handler);
|
Chris@16
|
500
|
Chris@16
|
501 /// Fork-related event notifications.
|
Chris@16
|
502 enum fork_event
|
Chris@16
|
503 {
|
Chris@16
|
504 /// Notify the io_service that the process is about to fork.
|
Chris@16
|
505 fork_prepare,
|
Chris@16
|
506
|
Chris@16
|
507 /// Notify the io_service that the process has forked and is the parent.
|
Chris@16
|
508 fork_parent,
|
Chris@16
|
509
|
Chris@16
|
510 /// Notify the io_service that the process has forked and is the child.
|
Chris@16
|
511 fork_child
|
Chris@16
|
512 };
|
Chris@16
|
513
|
Chris@16
|
514 /// Notify the io_service of a fork-related event.
|
Chris@16
|
515 /**
|
Chris@16
|
516 * This function is used to inform the io_service that the process is about
|
Chris@16
|
517 * to fork, or has just forked. This allows the io_service, and the services
|
Chris@16
|
518 * it contains, to perform any necessary housekeeping to ensure correct
|
Chris@16
|
519 * operation following a fork.
|
Chris@16
|
520 *
|
Chris@16
|
521 * This function must not be called while any other io_service function, or
|
Chris@16
|
522 * any function on an I/O object associated with the io_service, is being
|
Chris@16
|
523 * called in another thread. It is, however, safe to call this function from
|
Chris@16
|
524 * within a completion handler, provided no other thread is accessing the
|
Chris@16
|
525 * io_service.
|
Chris@16
|
526 *
|
Chris@16
|
527 * @param event A fork-related event.
|
Chris@16
|
528 *
|
Chris@16
|
529 * @throws boost::system::system_error Thrown on failure. If the notification
|
Chris@16
|
530 * fails the io_service object should no longer be used and should be
|
Chris@16
|
531 * destroyed.
|
Chris@16
|
532 *
|
Chris@16
|
533 * @par Example
|
Chris@16
|
534 * The following code illustrates how to incorporate the notify_fork()
|
Chris@16
|
535 * function:
|
Chris@16
|
536 * @code my_io_service.notify_fork(boost::asio::io_service::fork_prepare);
|
Chris@16
|
537 * if (fork() == 0)
|
Chris@16
|
538 * {
|
Chris@16
|
539 * // This is the child process.
|
Chris@16
|
540 * my_io_service.notify_fork(boost::asio::io_service::fork_child);
|
Chris@16
|
541 * }
|
Chris@16
|
542 * else
|
Chris@16
|
543 * {
|
Chris@16
|
544 * // This is the parent process.
|
Chris@16
|
545 * my_io_service.notify_fork(boost::asio::io_service::fork_parent);
|
Chris@16
|
546 * } @endcode
|
Chris@16
|
547 *
|
Chris@16
|
548 * @note For each service object @c svc in the io_service set, performs
|
Chris@16
|
549 * <tt>svc->fork_service();</tt>. When processing the fork_prepare event,
|
Chris@16
|
550 * services are visited in reverse order of the beginning of service object
|
Chris@16
|
551 * lifetime. Otherwise, services are visited in order of the beginning of
|
Chris@16
|
552 * service object lifetime.
|
Chris@16
|
553 */
|
Chris@16
|
554 BOOST_ASIO_DECL void notify_fork(boost::asio::io_service::fork_event event);
|
Chris@16
|
555
|
Chris@16
|
556 /// Obtain the service object corresponding to the given type.
|
Chris@16
|
557 /**
|
Chris@16
|
558 * This function is used to locate a service object that corresponds to
|
Chris@16
|
559 * the given service type. If there is no existing implementation of the
|
Chris@16
|
560 * service, then the io_service will create a new instance of the service.
|
Chris@16
|
561 *
|
Chris@16
|
562 * @param ios The io_service object that owns the service.
|
Chris@16
|
563 *
|
Chris@16
|
564 * @return The service interface implementing the specified service type.
|
Chris@16
|
565 * Ownership of the service interface is not transferred to the caller.
|
Chris@16
|
566 */
|
Chris@16
|
567 template <typename Service>
|
Chris@16
|
568 friend Service& use_service(io_service& ios);
|
Chris@16
|
569
|
Chris@16
|
570 /// Add a service object to the io_service.
|
Chris@16
|
571 /**
|
Chris@16
|
572 * This function is used to add a service to the io_service.
|
Chris@16
|
573 *
|
Chris@16
|
574 * @param ios The io_service object that owns the service.
|
Chris@16
|
575 *
|
Chris@16
|
576 * @param svc The service object. On success, ownership of the service object
|
Chris@16
|
577 * is transferred to the io_service. When the io_service object is destroyed,
|
Chris@16
|
578 * it will destroy the service object by performing:
|
Chris@16
|
579 * @code delete static_cast<io_service::service*>(svc) @endcode
|
Chris@16
|
580 *
|
Chris@16
|
581 * @throws boost::asio::service_already_exists Thrown if a service of the
|
Chris@16
|
582 * given type is already present in the io_service.
|
Chris@16
|
583 *
|
Chris@16
|
584 * @throws boost::asio::invalid_service_owner Thrown if the service's owning
|
Chris@16
|
585 * io_service is not the io_service object specified by the ios parameter.
|
Chris@16
|
586 */
|
Chris@16
|
587 template <typename Service>
|
Chris@16
|
588 friend void add_service(io_service& ios, Service* svc);
|
Chris@16
|
589
|
Chris@16
|
590 /// Determine if an io_service contains a specified service type.
|
Chris@16
|
591 /**
|
Chris@16
|
592 * This function is used to determine whether the io_service contains a
|
Chris@16
|
593 * service object corresponding to the given service type.
|
Chris@16
|
594 *
|
Chris@16
|
595 * @param ios The io_service object that owns the service.
|
Chris@16
|
596 *
|
Chris@16
|
597 * @return A boolean indicating whether the io_service contains the service.
|
Chris@16
|
598 */
|
Chris@16
|
599 template <typename Service>
|
Chris@16
|
600 friend bool has_service(io_service& ios);
|
Chris@16
|
601
|
Chris@16
|
602 private:
|
Chris@16
|
603 #if defined(BOOST_ASIO_WINDOWS) || defined(__CYGWIN__)
|
Chris@16
|
604 detail::winsock_init<> init_;
|
Chris@16
|
605 #elif defined(__sun) || defined(__QNX__) || defined(__hpux) || defined(_AIX) \
|
Chris@16
|
606 || defined(__osf__)
|
Chris@16
|
607 detail::signal_init<> init_;
|
Chris@16
|
608 #endif
|
Chris@16
|
609
|
Chris@16
|
610 // The service registry.
|
Chris@16
|
611 boost::asio::detail::service_registry* service_registry_;
|
Chris@16
|
612
|
Chris@16
|
613 // The implementation.
|
Chris@16
|
614 impl_type& impl_;
|
Chris@16
|
615 };
|
Chris@16
|
616
|
Chris@16
|
617 /// Class to inform the io_service when it has work to do.
|
Chris@16
|
618 /**
|
Chris@16
|
619 * The work class is used to inform the io_service when work starts and
|
Chris@16
|
620 * finishes. This ensures that the io_service object's run() function will not
|
Chris@16
|
621 * exit while work is underway, and that it does exit when there is no
|
Chris@16
|
622 * unfinished work remaining.
|
Chris@16
|
623 *
|
Chris@16
|
624 * The work class is copy-constructible so that it may be used as a data member
|
Chris@16
|
625 * in a handler class. It is not assignable.
|
Chris@16
|
626 */
|
Chris@16
|
627 class io_service::work
|
Chris@16
|
628 {
|
Chris@16
|
629 public:
|
Chris@16
|
630 /// Constructor notifies the io_service that work is starting.
|
Chris@16
|
631 /**
|
Chris@16
|
632 * The constructor is used to inform the io_service that some work has begun.
|
Chris@16
|
633 * This ensures that the io_service object's run() function will not exit
|
Chris@16
|
634 * while the work is underway.
|
Chris@16
|
635 */
|
Chris@16
|
636 explicit work(boost::asio::io_service& io_service);
|
Chris@16
|
637
|
Chris@16
|
638 /// Copy constructor notifies the io_service that work is starting.
|
Chris@16
|
639 /**
|
Chris@16
|
640 * The constructor is used to inform the io_service that some work has begun.
|
Chris@16
|
641 * This ensures that the io_service object's run() function will not exit
|
Chris@16
|
642 * while the work is underway.
|
Chris@16
|
643 */
|
Chris@16
|
644 work(const work& other);
|
Chris@16
|
645
|
Chris@16
|
646 /// Destructor notifies the io_service that the work is complete.
|
Chris@16
|
647 /**
|
Chris@16
|
648 * The destructor is used to inform the io_service that some work has
|
Chris@16
|
649 * finished. Once the count of unfinished work reaches zero, the io_service
|
Chris@16
|
650 * object's run() function is permitted to exit.
|
Chris@16
|
651 */
|
Chris@16
|
652 ~work();
|
Chris@16
|
653
|
Chris@16
|
654 /// Get the io_service associated with the work.
|
Chris@16
|
655 boost::asio::io_service& get_io_service();
|
Chris@16
|
656
|
Chris@16
|
657 private:
|
Chris@16
|
658 // Prevent assignment.
|
Chris@16
|
659 void operator=(const work& other);
|
Chris@16
|
660
|
Chris@16
|
661 // The io_service implementation.
|
Chris@16
|
662 detail::io_service_impl& io_service_impl_;
|
Chris@16
|
663 };
|
Chris@16
|
664
|
Chris@16
|
665 /// Class used to uniquely identify a service.
|
Chris@16
|
666 class io_service::id
|
Chris@16
|
667 : private noncopyable
|
Chris@16
|
668 {
|
Chris@16
|
669 public:
|
Chris@16
|
670 /// Constructor.
|
Chris@16
|
671 id() {}
|
Chris@16
|
672 };
|
Chris@16
|
673
|
Chris@16
|
674 /// Base class for all io_service services.
|
Chris@16
|
675 class io_service::service
|
Chris@16
|
676 : private noncopyable
|
Chris@16
|
677 {
|
Chris@16
|
678 public:
|
Chris@16
|
679 /// Get the io_service object that owns the service.
|
Chris@16
|
680 boost::asio::io_service& get_io_service();
|
Chris@16
|
681
|
Chris@16
|
682 protected:
|
Chris@16
|
683 /// Constructor.
|
Chris@16
|
684 /**
|
Chris@16
|
685 * @param owner The io_service object that owns the service.
|
Chris@16
|
686 */
|
Chris@16
|
687 BOOST_ASIO_DECL service(boost::asio::io_service& owner);
|
Chris@16
|
688
|
Chris@16
|
689 /// Destructor.
|
Chris@16
|
690 BOOST_ASIO_DECL virtual ~service();
|
Chris@16
|
691
|
Chris@16
|
692 private:
|
Chris@16
|
693 /// Destroy all user-defined handler objects owned by the service.
|
Chris@16
|
694 virtual void shutdown_service() = 0;
|
Chris@16
|
695
|
Chris@16
|
696 /// Handle notification of a fork-related event to perform any necessary
|
Chris@16
|
697 /// housekeeping.
|
Chris@16
|
698 /**
|
Chris@16
|
699 * This function is not a pure virtual so that services only have to
|
Chris@16
|
700 * implement it if necessary. The default implementation does nothing.
|
Chris@16
|
701 */
|
Chris@16
|
702 BOOST_ASIO_DECL virtual void fork_service(
|
Chris@16
|
703 boost::asio::io_service::fork_event event);
|
Chris@16
|
704
|
Chris@16
|
705 friend class boost::asio::detail::service_registry;
|
Chris@16
|
706 struct key
|
Chris@16
|
707 {
|
Chris@16
|
708 key() : type_info_(0), id_(0) {}
|
Chris@16
|
709 const std::type_info* type_info_;
|
Chris@16
|
710 const boost::asio::io_service::id* id_;
|
Chris@16
|
711 } key_;
|
Chris@16
|
712
|
Chris@16
|
713 boost::asio::io_service& owner_;
|
Chris@16
|
714 service* next_;
|
Chris@16
|
715 };
|
Chris@16
|
716
|
Chris@16
|
717 /// Exception thrown when trying to add a duplicate service to an io_service.
|
Chris@16
|
718 class service_already_exists
|
Chris@16
|
719 : public std::logic_error
|
Chris@16
|
720 {
|
Chris@16
|
721 public:
|
Chris@16
|
722 BOOST_ASIO_DECL service_already_exists();
|
Chris@16
|
723 };
|
Chris@16
|
724
|
Chris@16
|
725 /// Exception thrown when trying to add a service object to an io_service where
|
Chris@16
|
726 /// the service has a different owner.
|
Chris@16
|
727 class invalid_service_owner
|
Chris@16
|
728 : public std::logic_error
|
Chris@16
|
729 {
|
Chris@16
|
730 public:
|
Chris@16
|
731 BOOST_ASIO_DECL invalid_service_owner();
|
Chris@16
|
732 };
|
Chris@16
|
733
|
Chris@16
|
734 namespace detail {
|
Chris@16
|
735
|
Chris@16
|
736 // Special derived service id type to keep classes header-file only.
|
Chris@16
|
737 template <typename Type>
|
Chris@16
|
738 class service_id
|
Chris@16
|
739 : public boost::asio::io_service::id
|
Chris@16
|
740 {
|
Chris@16
|
741 };
|
Chris@16
|
742
|
Chris@16
|
743 // Special service base class to keep classes header-file only.
|
Chris@16
|
744 template <typename Type>
|
Chris@16
|
745 class service_base
|
Chris@16
|
746 : public boost::asio::io_service::service
|
Chris@16
|
747 {
|
Chris@16
|
748 public:
|
Chris@16
|
749 static boost::asio::detail::service_id<Type> id;
|
Chris@16
|
750
|
Chris@16
|
751 // Constructor.
|
Chris@16
|
752 service_base(boost::asio::io_service& io_service)
|
Chris@16
|
753 : boost::asio::io_service::service(io_service)
|
Chris@16
|
754 {
|
Chris@16
|
755 }
|
Chris@16
|
756 };
|
Chris@16
|
757
|
Chris@16
|
758 template <typename Type>
|
Chris@16
|
759 boost::asio::detail::service_id<Type> service_base<Type>::id;
|
Chris@16
|
760
|
Chris@16
|
761 } // namespace detail
|
Chris@16
|
762 } // namespace asio
|
Chris@16
|
763 } // namespace boost
|
Chris@16
|
764
|
Chris@16
|
765 #include <boost/asio/detail/pop_options.hpp>
|
Chris@16
|
766
|
Chris@16
|
767 #include <boost/asio/impl/io_service.hpp>
|
Chris@16
|
768 #if defined(BOOST_ASIO_HEADER_ONLY)
|
Chris@16
|
769 # include <boost/asio/impl/io_service.ipp>
|
Chris@16
|
770 #endif // defined(BOOST_ASIO_HEADER_ONLY)
|
Chris@16
|
771
|
Chris@16
|
772 #endif // BOOST_ASIO_IO_SERVICE_HPP
|