Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext

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:

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.
  }
}
Stopping the io_service from running out of work

Some applications may need to prevent an io_service'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 io_service::work:

boost::asio::io_service io_service;
boost::asio::io_service::work work(io_service);
... 

To effect a shutdown, the application will then need to call the io_service's stop() member function. This will cause the io_servicerun() 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.

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. 

PrevUpHomeNext