| Home | Libraries | People | FAQ | More

### io_service

Provides core I/O functionality.

    class io_service :
      noncopyable

##### Types

Name | Description
--- | ---
id | Class used to uniquely identify a service.
service | Base class for all io_service services.
strand | Provides serialised handler execution.
work | Class to inform the io_service when it has work to do.

##### Member Functions

Name | Description
--- | ---
dispatch | Request the io_service to invoke the given handler.
io_service | Constructor.
poll | Run the io_service's event processing loop to execute ready handlers.
poll_one | Run the io_service's event processing loop to execute one ready handler.
post | Request the io_service to invoke the given handler and return immediately.
reset | Reset the io_service in preparation for a subsequent run() invocation.
run | Run the io_service's event processing loop.
run_one | Run the io_service's event processing loop to execute at most one handler.
stop | Stop the io_service's event processing loop.
wrap | Create a new handler that automatically dispatches the wrapped handler on the io_service.
~io_service | Destructor.

##### Friends

Name | Description
--- | ---
add_service | Add a service object to the io_service.
has_service | Determine if an io_service contains a specified service type.
use_service | Obtain the service object corresponding to the given type.

The io_service class provides the core I/O functionality for users of the asynchronous I/O objects, including:

- boost::asio::ip::tcp::socket
- boost::asio::ip::tcp::acceptor
- boost::asio::ip::udp::socket
- boost::asio::deadline_timer.

The io_service class also includes facilities intended for developers of custom asynchronous services.

##### Thread Safety

Distinct objects: Safe.

Shared objects: Safe, with the exception that calling reset() while there are unfinished run() calls results in undefined behaviour.

##### 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 boost::asio::io_service::run(), boost::asio::io_service::run_one(), boost::asio::io_service::poll() or boost::asio::io_service::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 boost::asio::io_service::run(), boost::asio::io_service::run_one(), boost::asio::io_service::poll() or boost::asio::io_service::poll_one() call may be restarted without the need for an intervening call to boost::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:

    boost::asio::io_service io_service;
    ...
    for (;;)
    {
      try
      {
        io_service.run();
        break; // run() exited normally
      }
      catch (my_exception& e)
      {
        // Deal with exception as appropriate.
      }
    }