| // |
| // io_service.hpp |
| // ~~~~~~~~~~~~~~ |
| // |
| // Copyright (c) 2003-2010 Christopher M. Kohlhoff (chris at kohlhoff dot com) |
| // |
| // Distributed under the Boost Software License, Version 1.0. (See accompanying |
| // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| // |
| |
| #ifndef BOOST_ASIO_IO_SERVICE_HPP |
| #define BOOST_ASIO_IO_SERVICE_HPP |
| |
| #if defined(_MSC_VER) && (_MSC_VER >= 1200) |
| # pragma once |
| #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) |
| |
| #include <boost/asio/detail/config.hpp> |
| #include <cstddef> |
| #include <stdexcept> |
| #include <typeinfo> |
| #include <boost/asio/detail/noncopyable.hpp> |
| #include <boost/asio/detail/service_registry_fwd.hpp> |
| #include <boost/asio/detail/wrapped_handler.hpp> |
| #include <boost/system/error_code.hpp> |
| |
| #if defined(BOOST_ASIO_HAS_IOCP) |
| # include <boost/asio/detail/win_iocp_io_service_fwd.hpp> |
| #else |
| # include <boost/asio/detail/task_io_service_fwd.hpp> |
| #endif |
| |
| #if defined(BOOST_WINDOWS) || defined(__CYGWIN__) |
| # include <boost/asio/detail/winsock_init.hpp> |
| #elif defined(__sun) || defined(__QNX__) || defined(__hpux) || defined(_AIX) \ |
| || defined(__osf__) |
| # include <boost/asio/detail/signal_init.hpp> |
| #endif |
| |
| #include <boost/asio/detail/push_options.hpp> |
| |
| namespace boost { |
| namespace asio { |
| |
| class io_service; |
| template <typename Service> Service& use_service(io_service& ios); |
| template <typename Service> void add_service(io_service& ios, Service* svc); |
| template <typename Service> bool has_service(io_service& ios); |
| |
| #if defined(BOOST_ASIO_HAS_IOCP) |
| namespace detail { typedef win_iocp_io_service io_service_impl; } |
| #else |
| namespace detail { typedef task_io_service io_service_impl; } |
| #endif |
| |
| /// Provides core I/O functionality. |
| /** |
| * The io_service class provides the core I/O functionality for users of the |
| * asynchronous I/O objects, including: |
| * |
| * @li boost::asio::ip::tcp::socket |
| * @li boost::asio::ip::tcp::acceptor |
| * @li boost::asio::ip::udp::socket |
| * @li boost::asio::deadline_timer. |
| * |
| * The io_service class also includes facilities intended for developers of |
| * custom asynchronous services. |
| * |
| * @par Thread Safety |
| * @e Distinct @e objects: Safe.@n |
| * @e Shared @e objects: Safe, with the exception that calling reset() while |
| * there are unfinished run(), run_one(), poll() or poll_one() calls results in |
| * undefined behaviour. |
| * |
| * @par Concepts: |
| * Dispatcher. |
| * |
| * @par Synchronous and asynchronous operations |
| * |
| * Synchronous operations on I/O objects implicitly run the io_service object |
| * for an individual operation. The io_service functions run(), run_one(), |
| * poll() or poll_one() must be called for the io_service to perform |
| * asynchronous operations on behalf of a C++ program. Notification that an |
| * asynchronous operation has completed is delivered by invocation of the |
| * associated handler. Handlers are invoked only by a thread that is currently |
| * calling any overload of run(), run_one(), poll() or poll_one() for the |
| * io_service. |
| * |
| * @par Effect of exceptions thrown from handlers |
| * |
| * If an exception is thrown from a handler, the exception is allowed to |
| * propagate through the throwing thread's invocation of run(), run_one(), |
| * poll() or poll_one(). No other threads that are calling any of these |
| * functions are affected. It is then the responsibility of the application to |
| * catch the exception. |
| * |
| * After the exception has been caught, the run(), run_one(), poll() or |
| * poll_one() call may be restarted @em without the need for an intervening |
| * call to reset(). This allows the thread to rejoin the io_service object's |
| * thread pool without impacting any other threads in the pool. |
| * |
| * For example: |
| * |
| * @code |
| * boost::asio::io_service io_service; |
| * ... |
| * for (;;) |
| * { |
| * try |
| * { |
| * io_service.run(); |
| * break; // run() exited normally |
| * } |
| * catch (my_exception& e) |
| * { |
| * // Deal with exception as appropriate. |
| * } |
| * } |
| * @endcode |
| * |
| * @par Stopping the io_service from running out of work |
| * |
| * Some applications may need to prevent an io_service object's run() call from |
| * returning when there is no more work to do. For example, the io_service may |
| * be being run in a background thread that is launched prior to the |
| * application's asynchronous operations. The run() call may be kept running by |
| * creating an object of type boost::asio::io_service::work: |
| * |
| * @code boost::asio::io_service io_service; |
| * boost::asio::io_service::work work(io_service); |
| * ... @endcode |
| * |
| * To effect a shutdown, the application will then need to call the io_service |
| * object's stop() member function. This will cause the io_service run() call |
| * to return as soon as possible, abandoning unfinished operations and without |
| * permitting ready handlers to be dispatched. |
| * |
| * Alternatively, if the application requires that all operations and handlers |
| * be allowed to finish normally, the work object may be explicitly destroyed. |
| * |
| * @code boost::asio::io_service io_service; |
| * auto_ptr<boost::asio::io_service::work> work( |
| * new boost::asio::io_service::work(io_service)); |
| * ... |
| * work.reset(); // Allow run() to exit. @endcode |
| * |
| * @par The io_service class and I/O services |
| * |
| * Class io_service implements an extensible, type-safe, polymorphic set of I/O |
| * services, indexed by service type. An object of class io_service must be |
| * initialised before I/O objects such as sockets, resolvers and timers can be |
| * used. These I/O objects are distinguished by having constructors that accept |
| * an @c io_service& parameter. |
| * |
| * I/O services exist to manage the logical interface to the operating system on |
| * behalf of the I/O objects. In particular, there are resources that are shared |
| * across a class of I/O objects. For example, timers may be implemented in |
| * terms of a single timer queue. The I/O services manage these shared |
| * resources. |
| * |
| * Access to the services of an io_service is via three function templates, |
| * use_service(), add_service() and has_service(). |
| * |
| * In a call to @c use_service<Service>(), the type argument chooses a service, |
| * making available all members of the named type. If @c Service is not present |
| * in an io_service, an object of type @c Service is created and added to the |
| * io_service. A C++ program can check if an io_service implements a |
| * particular service with the function template @c has_service<Service>(). |
| * |
| * Service objects may be explicitly added to an io_service using the function |
| * template @c add_service<Service>(). If the @c Service is already present, the |
| * service_already_exists exception is thrown. If the owner of the service is |
| * not the same object as the io_service parameter, the invalid_service_owner |
| * exception is thrown. |
| * |
| * Once a service reference is obtained from an io_service object by calling |
| * use_service(), that reference remains usable as long as the owning io_service |
| * object exists. |
| * |
| * All I/O service implementations have io_service::service as a public base |
| * class. Custom I/O services may be implemented by deriving from this class and |
| * then added to an io_service using the facilities described above. |
| */ |
| class io_service |
| : private noncopyable |
| { |
| private: |
| typedef detail::io_service_impl impl_type; |
| #if defined(BOOST_ASIO_HAS_IOCP) |
| friend class detail::win_iocp_overlapped_ptr; |
| #endif |
| |
| public: |
| class work; |
| friend class work; |
| |
| class id; |
| |
| class service; |
| |
| class strand; |
| |
| /// Constructor. |
| BOOST_ASIO_DECL io_service(); |
| |
| /// Constructor. |
| /** |
| * Construct with a hint about the required level of concurrency. |
| * |
| * @param concurrency_hint A suggestion to the implementation on how many |
| * threads it should allow to run simultaneously. |
| */ |
| BOOST_ASIO_DECL explicit io_service(std::size_t concurrency_hint); |
| |
| /// Destructor. |
| /** |
| * On destruction, the io_service performs the following sequence of |
| * operations: |
| * |
| * @li For each service object @c svc in the io_service set, in reverse order |
| * of the beginning of service object lifetime, performs |
| * @c svc->shutdown_service(). |
| * |
| * @li Uninvoked handler objects that were scheduled for deferred invocation |
| * on the io_service, or any associated strand, are destroyed. |
| * |
| * @li For each service object @c svc in the io_service set, in reverse order |
| * of the beginning of service object lifetime, performs |
| * <tt>delete static_cast<io_service::service*>(svc)</tt>. |
| * |
| * @note The destruction sequence described above permits programs to |
| * simplify their resource management by using @c shared_ptr<>. Where an |
| * object's lifetime is tied to the lifetime of a connection (or some other |
| * sequence of asynchronous operations), a @c shared_ptr to the object would |
| * be bound into the handlers for all asynchronous operations associated with |
| * it. This works as follows: |
| * |
| * @li When a single connection ends, all associated asynchronous operations |
| * complete. The corresponding handler objects are destroyed, and all |
| * @c shared_ptr references to the objects are destroyed. |
| * |
| * @li To shut down the whole program, the io_service function stop() is |
| * called to terminate any run() calls as soon as possible. The io_service |
| * destructor defined above destroys all handlers, causing all @c shared_ptr |
| * references to all connection objects to be destroyed. |
| */ |
| BOOST_ASIO_DECL ~io_service(); |
| |
| /// Run the io_service object's event processing loop. |
| /** |
| * The run() function blocks until all work has finished and there are no |
| * more handlers to be dispatched, or until the io_service has been stopped. |
| * |
| * Multiple threads may call the run() function to set up a pool of threads |
| * from which the io_service may execute handlers. All threads that are |
| * waiting in the pool are equivalent and the io_service may choose any one |
| * of them to invoke a handler. |
| * |
| * The run() function may be safely called again once it has completed only |
| * after a call to reset(). |
| * |
| * @return The number of handlers that were executed. |
| * |
| * @throws boost::system::system_error Thrown on failure. |
| * |
| * @note The run() function must not be called from a thread that is currently |
| * calling one of run(), run_one(), poll() or poll_one() on the same |
| * io_service object. |
| * |
| * The poll() function may also be used to dispatch ready handlers, but |
| * without blocking. |
| */ |
| BOOST_ASIO_DECL std::size_t run(); |
| |
| /// Run the io_service object's event processing loop. |
| /** |
| * The run() function blocks until all work has finished and there are no |
| * more handlers to be dispatched, or until the io_service has been stopped. |
| * |
| * Multiple threads may call the run() function to set up a pool of threads |
| * from which the io_service may execute handlers. All threads that are |
| * waiting in the pool are equivalent and the io_service may choose any one |
| * of them to invoke a handler. |
| * |
| * The run() function may be safely called again once it has completed only |
| * after a call to reset(). |
| * |
| * @param ec Set to indicate what error occurred, if any. |
| * |
| * @return The number of handlers that were executed. |
| * |
| * @note The run() function must not be called from a thread that is currently |
| * calling one of run(), run_one(), poll() or poll_one() on the same |
| * io_service object. |
| * |
| * The poll() function may also be used to dispatch ready handlers, but |
| * without blocking. |
| */ |
| BOOST_ASIO_DECL std::size_t run(boost::system::error_code& ec); |
| |
| /// Run the io_service object's event processing loop to execute at most one |
| /// handler. |
| /** |
| * The run_one() function blocks until one handler has been dispatched, or |
| * until the io_service has been stopped. |
| * |
| * @return The number of handlers that were executed. |
| * |
| * @throws boost::system::system_error Thrown on failure. |
| */ |
| BOOST_ASIO_DECL std::size_t run_one(); |
| |
| /// Run the io_service object's event processing loop to execute at most one |
| /// handler. |
| /** |
| * The run_one() function blocks until one handler has been dispatched, or |
| * until the io_service has been stopped. |
| * |
| * @param ec Set to indicate what error occurred, if any. |
| * |
| * @return The number of handlers that were executed. |
| */ |
| BOOST_ASIO_DECL std::size_t run_one(boost::system::error_code& ec); |
| |
| /// Run the io_service object's event processing loop to execute ready |
| /// handlers. |
| /** |
| * The poll() function runs handlers that are ready to run, without blocking, |
| * until the io_service has been stopped or there are no more ready handlers. |
| * |
| * @return The number of handlers that were executed. |
| * |
| * @throws boost::system::system_error Thrown on failure. |
| */ |
| BOOST_ASIO_DECL std::size_t poll(); |
| |
| /// Run the io_service object's event processing loop to execute ready |
| /// handlers. |
| /** |
| * The poll() function runs handlers that are ready to run, without blocking, |
| * until the io_service has been stopped or there are no more ready handlers. |
| * |
| * @param ec Set to indicate what error occurred, if any. |
| * |
| * @return The number of handlers that were executed. |
| */ |
| BOOST_ASIO_DECL std::size_t poll(boost::system::error_code& ec); |
| |
| /// Run the io_service object's event processing loop to execute one ready |
| /// handler. |
| /** |
| * The poll_one() function runs at most one handler that is ready to run, |
| * without blocking. |
| * |
| * @return The number of handlers that were executed. |
| * |
| * @throws boost::system::system_error Thrown on failure. |
| */ |
| BOOST_ASIO_DECL std::size_t poll_one(); |
| |
| /// Run the io_service object's event processing loop to execute one ready |
| /// handler. |
| /** |
| * The poll_one() function runs at most one handler that is ready to run, |
| * without blocking. |
| * |
| * @param ec Set to indicate what error occurred, if any. |
| * |
| * @return The number of handlers that were executed. |
| */ |
| BOOST_ASIO_DECL std::size_t poll_one(boost::system::error_code& ec); |
| |
| /// Stop the io_service object's event processing loop. |
| /** |
| * This function does not block, but instead simply signals the io_service to |
| * stop. All invocations of its run() or run_one() member functions should |
| * return as soon as possible. Subsequent calls to run(), run_one(), poll() |
| * or poll_one() will return immediately until reset() is called. |
| */ |
| BOOST_ASIO_DECL void stop(); |
| |
| /// Reset the io_service in preparation for a subsequent run() invocation. |
| /** |
| * This function must be called prior to any second or later set of |
| * invocations of the run(), run_one(), poll() or poll_one() functions when a |
| * previous invocation of these functions returned due to the io_service |
| * being stopped or running out of work. This function allows the io_service |
| * to reset any internal state, such as a "stopped" flag. |
| * |
| * This function must not be called while there are any unfinished calls to |
| * the run(), run_one(), poll() or poll_one() functions. |
| */ |
| BOOST_ASIO_DECL void reset(); |
| |
| /// Request the io_service to invoke the given handler. |
| /** |
| * This function is used to ask the io_service to execute the given handler. |
| * |
| * The io_service guarantees that the handler will only be called in a thread |
| * in which the run(), run_one(), poll() or poll_one() member functions is |
| * currently being invoked. The handler may be executed inside this function |
| * if the guarantee can be met. |
| * |
| * @param handler The handler to be called. The io_service will make |
| * a copy of the handler object as required. The function signature of the |
| * handler must be: @code void handler(); @endcode |
| * |
| * @note This function throws an exception only if: |
| * |
| * @li the handler's @c asio_handler_allocate function; or |
| * |
| * @li the handler's copy constructor |
| * |
| * throws an exception. |
| */ |
| template <typename CompletionHandler> |
| void dispatch(CompletionHandler handler); |
| |
| /// Request the io_service to invoke the given handler and return immediately. |
| /** |
| * This function is used to ask the io_service to execute the given handler, |
| * but without allowing the io_service to call the handler from inside this |
| * function. |
| * |
| * The io_service guarantees that the handler will only be called in a thread |
| * in which the run(), run_one(), poll() or poll_one() member functions is |
| * currently being invoked. |
| * |
| * @param handler The handler to be called. The io_service will make |
| * a copy of the handler object as required. The function signature of the |
| * handler must be: @code void handler(); @endcode |
| * |
| * @note This function throws an exception only if: |
| * |
| * @li the handler's @c asio_handler_allocate function; or |
| * |
| * @li the handler's copy constructor |
| * |
| * throws an exception. |
| */ |
| template <typename CompletionHandler> |
| void post(CompletionHandler handler); |
| |
| /// Create a new handler that automatically dispatches the wrapped handler |
| /// on the io_service. |
| /** |
| * This function is used to create a new handler function object that, when |
| * invoked, will automatically pass the wrapped handler to the io_service |
| * object's dispatch function. |
| * |
| * @param handler The handler to be wrapped. The io_service will make a copy |
| * of the handler object as required. The function signature of the handler |
| * must be: @code void handler(A1 a1, ... An an); @endcode |
| * |
| * @return A function object that, when invoked, passes the wrapped handler to |
| * the io_service object's dispatch function. Given a function object with the |
| * signature: |
| * @code R f(A1 a1, ... An an); @endcode |
| * If this function object is passed to the wrap function like so: |
| * @code io_service.wrap(f); @endcode |
| * then the return value is a function object with the signature |
| * @code void g(A1 a1, ... An an); @endcode |
| * that, when invoked, executes code equivalent to: |
| * @code io_service.dispatch(boost::bind(f, a1, ... an)); @endcode |
| */ |
| template <typename Handler> |
| #if defined(GENERATING_DOCUMENTATION) |
| unspecified |
| #else |
| detail::wrapped_handler<io_service&, Handler> |
| #endif |
| wrap(Handler handler); |
| |
| /// Obtain the service object corresponding to the given type. |
| /** |
| * This function is used to locate a service object that corresponds to |
| * the given service type. If there is no existing implementation of the |
| * service, then the io_service will create a new instance of the service. |
| * |
| * @param ios The io_service object that owns the service. |
| * |
| * @return The service interface implementing the specified service type. |
| * Ownership of the service interface is not transferred to the caller. |
| */ |
| template <typename Service> |
| friend Service& use_service(io_service& ios); |
| |
| /// Add a service object to the io_service. |
| /** |
| * This function is used to add a service to the io_service. |
| * |
| * @param ios The io_service object that owns the service. |
| * |
| * @param svc The service object. On success, ownership of the service object |
| * is transferred to the io_service. When the io_service object is destroyed, |
| * it will destroy the service object by performing: |
| * @code delete static_cast<io_service::service*>(svc) @endcode |
| * |
| * @throws boost::asio::service_already_exists Thrown if a service of the |
| * given type is already present in the io_service. |
| * |
| * @throws boost::asio::invalid_service_owner Thrown if the service's owning |
| * io_service is not the io_service object specified by the ios parameter. |
| */ |
| template <typename Service> |
| friend void add_service(io_service& ios, Service* svc); |
| |
| /// Determine if an io_service contains a specified service type. |
| /** |
| * This function is used to determine whether the io_service contains a |
| * service object corresponding to the given service type. |
| * |
| * @param ios The io_service object that owns the service. |
| * |
| * @return A boolean indicating whether the io_service contains the service. |
| */ |
| template <typename Service> |
| friend bool has_service(io_service& ios); |
| |
| private: |
| #if defined(BOOST_WINDOWS) || defined(__CYGWIN__) |
| detail::winsock_init<> init_; |
| #elif defined(__sun) || defined(__QNX__) || defined(__hpux) || defined(_AIX) \ |
| || defined(__osf__) |
| detail::signal_init<> init_; |
| #endif |
| |
| // The service registry. |
| boost::asio::detail::service_registry* service_registry_; |
| |
| // The implementation. |
| impl_type& impl_; |
| }; |
| |
| /// Class to inform the io_service when it has work to do. |
| /** |
| * The work class is used to inform the io_service when work starts and |
| * finishes. This ensures that the io_service object's run() function will not |
| * exit while work is underway, and that it does exit when there is no |
| * unfinished work remaining. |
| * |
| * The work class is copy-constructible so that it may be used as a data member |
| * in a handler class. It is not assignable. |
| */ |
| class io_service::work |
| { |
| public: |
| /// Constructor notifies the io_service that work is starting. |
| /** |
| * The constructor is used to inform the io_service that some work has begun. |
| * This ensures that the io_service object's run() function will not exit |
| * while the work is underway. |
| */ |
| explicit work(boost::asio::io_service& io_service); |
| |
| /// Copy constructor notifies the io_service that work is starting. |
| /** |
| * The constructor is used to inform the io_service that some work has begun. |
| * This ensures that the io_service object's run() function will not exit |
| * while the work is underway. |
| */ |
| work(const work& other); |
| |
| /// Destructor notifies the io_service that the work is complete. |
| /** |
| * The destructor is used to inform the io_service that some work has |
| * finished. Once the count of unfinished work reaches zero, the io_service |
| * object's run() function is permitted to exit. |
| */ |
| ~work(); |
| |
| /// (Deprecated: use get_io_service().) Get the io_service associated with the |
| /// work. |
| boost::asio::io_service& io_service(); |
| |
| /// Get the io_service associated with the work. |
| boost::asio::io_service& get_io_service(); |
| |
| private: |
| // Prevent assignment. |
| void operator=(const work& other); |
| |
| // The io_service. |
| boost::asio::io_service& io_service_; |
| }; |
| |
| /// Class used to uniquely identify a service. |
| class io_service::id |
| : private noncopyable |
| { |
| public: |
| /// Constructor. |
| id() {} |
| }; |
| |
| /// Base class for all io_service services. |
| class io_service::service |
| : private noncopyable |
| { |
| public: |
| /// (Deprecated: use get_io_service().) Get the io_service object that owns |
| /// the service. |
| boost::asio::io_service& io_service(); |
| |
| /// Get the io_service object that owns the service. |
| boost::asio::io_service& get_io_service(); |
| |
| protected: |
| /// Constructor. |
| /** |
| * @param owner The io_service object that owns the service. |
| */ |
| BOOST_ASIO_DECL service(boost::asio::io_service& owner); |
| |
| /// Destructor. |
| BOOST_ASIO_DECL virtual ~service(); |
| |
| private: |
| /// Destroy all user-defined handler objects owned by the service. |
| virtual void shutdown_service() = 0; |
| |
| friend class boost::asio::detail::service_registry; |
| struct key |
| { |
| key() : type_info_(0), id_(0) {} |
| const std::type_info* type_info_; |
| const boost::asio::io_service::id* id_; |
| } key_; |
| |
| boost::asio::io_service& owner_; |
| service* next_; |
| }; |
| |
| /// Exception thrown when trying to add a duplicate service to an io_service. |
| class service_already_exists |
| : public std::logic_error |
| { |
| public: |
| BOOST_ASIO_DECL service_already_exists(); |
| }; |
| |
| /// Exception thrown when trying to add a service object to an io_service where |
| /// the service has a different owner. |
| class invalid_service_owner |
| : public std::logic_error |
| { |
| public: |
| BOOST_ASIO_DECL invalid_service_owner(); |
| }; |
| |
| namespace detail { |
| |
| // Special derived service id type to keep classes header-file only. |
| template <typename Type> |
| class service_id |
| : public boost::asio::io_service::id |
| { |
| }; |
| |
| // Special service base class to keep classes header-file only. |
| template <typename Type> |
| class service_base |
| : public boost::asio::io_service::service |
| { |
| public: |
| static boost::asio::detail::service_id<Type> id; |
| |
| // Constructor. |
| service_base(boost::asio::io_service& io_service) |
| : boost::asio::io_service::service(io_service) |
| { |
| } |
| }; |
| |
| template <typename Type> |
| boost::asio::detail::service_id<Type> service_base<Type>::id; |
| |
| } // namespace detail |
| } // namespace asio |
| } // namespace boost |
| |
| #include <boost/asio/detail/pop_options.hpp> |
| |
| #include <boost/asio/impl/io_service.hpp> |
| #if defined(BOOST_ASIO_HEADER_ONLY) |
| # include <boost/asio/impl/io_service.ipp> |
| #endif // defined(BOOST_ASIO_HEADER_ONLY) |
| |
| #endif // BOOST_ASIO_IO_SERVICE_HPP |