Reference | Class Hierarchy | Class Index | Member Index |
The io_service class provides the core I/O functionality for users of the asynchronous I/O objects, including:
The io_service class also includes facilities intended for developers of custom asynchronous services.
After the exception has been caught, the asio::io_service::run(), asio::io_service::run_one(), asio::io_service::poll() or asio::io_service::poll_one() call may be restarted without the need for an intervening call to asio::io_service::reset(). This allows the thread to rejoin the io_service's thread pool without impacting any other threads in the pool.
For example:
asio::io_service io_service; ... for (;;) { try { io_service.run(); break; // run() exited normally } catch (my_exception& e) { // Deal with exception as appropriate. } }
Public Member Functions | |
io_service () | |
Constructor. | |
io_service (std::size_t concurrency_hint) | |
Constructor. | |
~io_service () | |
Destructor. | |
std::size_t | run () |
Run the io_service's event processing loop. | |
std::size_t | run (asio::error_code &ec) |
Run the io_service's event processing loop. | |
std::size_t | run_one () |
Run the io_service's event processing loop to execute at most one handler. | |
std::size_t | run_one (asio::error_code &ec) |
Run the io_service's event processing loop to execute at most one handler. | |
std::size_t | poll () |
Run the io_service's event processing loop to execute ready handlers. | |
std::size_t | poll (asio::error_code &ec) |
Run the io_service's event processing loop to execute ready handlers. | |
std::size_t | poll_one () |
Run the io_service's event processing loop to execute one ready handler. | |
std::size_t | poll_one (asio::error_code &ec) |
Run the io_service's event processing loop to execute one ready handler. | |
void | stop () |
Stop the io_service's event processing loop. | |
void | reset () |
Reset the io_service in preparation for a subsequent run() invocation. | |
template<typename CompletionHandler> | |
void | dispatch (CompletionHandler handler) |
Request the io_service to invoke the given handler. | |
template<typename CompletionHandler> | |
void | post (CompletionHandler handler) |
Request the io_service to invoke the given handler and return immediately. | |
template<typename Handler> | |
unspecified | wrap (Handler handler) |
Create a new handler that automatically dispatches the wrapped handler on the io_service. | |
Friends | |
template<typename Service> | |
Service & | use_service (io_service &ios) |
Obtain the service object corresponding to the given type. | |
template<typename Service> | |
void | add_service (io_service &ios, Service *svc) |
Add a service object to the io_service. | |
template<typename Service> | |
bool | has_service (io_service &ios) |
Determine if an io_service contains a specified service type. | |
Classes | |
class | id |
Class used to uniquely identify a service. More... | |
class | service |
Base class for all io_service services. More... | |
class | strand |
Provides serialised handler execution. More... | |
class | work |
Class to inform the io_service when it has work to do. More... |
asio::io_service::io_service | ( | ) |
Constructor.
asio::io_service::io_service | ( | std::size_t | concurrency_hint | ) | [explicit] |
Constructor.
Construct with a hint about the required level of concurrency.
concurrency_hint | A suggestion to the implementation on how many threads it should allow to run simultaneously. |
asio::io_service::~io_service | ( | ) |
Destructor.
std::size_t asio::io_service::run | ( | ) |
Run the io_service'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().
asio::system_error | Thrown on failure. |
std::size_t asio::io_service::run | ( | asio::error_code & | ec | ) |
Run the io_service'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().
ec | Set to indicate what error occurred, if any. |
std::size_t asio::io_service::run_one | ( | ) |
Run the io_service'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.
asio::system_error | Thrown on failure. |
std::size_t asio::io_service::run_one | ( | asio::error_code & | ec | ) |
Run the io_service'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.
ec | Set to indicate what error occurred, if any. |
std::size_t asio::io_service::poll | ( | ) |
Run the io_service'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.
asio::system_error | Thrown on failure. |
std::size_t asio::io_service::poll | ( | asio::error_code & | ec | ) |
Run the io_service'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.
ec | Set to indicate what error occurred, if any. |
std::size_t asio::io_service::poll_one | ( | ) |
Run the io_service'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.
asio::system_error | Thrown on failure. |
std::size_t asio::io_service::poll_one | ( | asio::error_code & | ec | ) |
Run the io_service'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.
ec | Set to indicate what error occurred, if any. |
void asio::io_service::stop | ( | ) |
Stop the io_service'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.
void asio::io_service::reset | ( | ) |
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.
void asio::io_service::dispatch | ( | Handler | handler | ) |
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.
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: void handler();
|
void asio::io_service::post | ( | Handler | 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.
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: void handler();
|
unspecified asio::io_service::wrap | ( | Handler | 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's dispatch function.
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: void handler(A1 a1, ... An an);
|
R f(A1 a1, ... An an);
io_service.wrap(f);
void g(A1 a1, ... An an);
io_service.dispatch(boost::bind(f, a1, ... an));
Service& use_service | ( | io_service & | ios | ) | [friend] |
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.
ios | The io_service object that owns the service. |
void add_service | ( | io_service & | ios, | |
Service * | svc | |||
) | [friend] |
Add a service object to the io_service.
This function is used to add a service to the io_service.
ios | The io_service object that owns the service. | |
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: delete static_cast<io_service::service*>(svc) |
asio::service_already_exists | Thrown if a service of the given type is already present in the io_service. | |
asio::invalid_service_owner | Thrown if the service's owning io_service is not the io_service object specified by the ios parameter. |
bool has_service | ( | io_service & | ios | ) | [friend] |
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.
ios | The io_service object that owns the service. |