io_service

Provides core I/O functionality.

class io_service :
  public execution_context

Types

Name	Description
executor_type	Executor used to submit functions to an io_service.
service	Base class for all io_service services.
strand	Provides serialised handler execution.
work	(Deprecated: Use executor_work.) Class to inform the io_service when it has work to do.
fork_event	Fork-related event notifications.

Member Functions

Name	Description
dispatch	(Deprecated: Use asio::dispatch().) Request the io_service to invoke the given handler.
get_executor	Obtains the executor associated with the io_service.
io_service	Constructor.
notify_fork	Notify the execution_context of a fork-related event.
poll	Run the io_service object's event processing loop to execute ready handlers.
poll_one	Run the io_service object's event processing loop to execute one ready handler.
post	(Deprecated: Use asio::post().) Request the io_service to invoke the given handler and return immediately.
reset	(Deprecated: Use restart().) Reset the io_service in preparation for a subsequent run() invocation.
restart	Restart the io_service in preparation for a subsequent run() invocation.
run	Run the io_service object's event processing loop.
run_one	Run the io_service object's event processing loop to execute at most one handler.
stop	Stop the io_service object's event processing loop.
stopped	Determine whether the io_service object has been stopped.
wrap	(Deprecated: Use asio::wrap().) Create a new handler that automatically dispatches the wrapped handler on the io_service.
~io_service	Destructor.

Protected Member Functions

Name	Description
destroy_context	Destroys all services in the context.
shutdown_context	Shuts down all services in the context.

Friends

Name	Description
add_service	(Deprecated: Use make_service().) Add a service object to the execution_context.
has_service	Determine if an execution_context contains a specified service type.
make_service	Creates a service object and adds it to the execution_context.
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:

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

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

Shared objects: Safe, with the specific exceptions of the restart() and notify_fork() functions. Calling restart() while there are unfinished run(), run_one(), poll() or poll_one() calls results in undefined behaviour. The notify_fork() function should not be called while any io_service function, or any function on an I/O object that is associated with the io_service, is being called in another thread.

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.

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 without the need for an intervening call to restart(). This allows the thread to rejoin the io_service object'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.
  }
}

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 io_service::work:

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

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.

asio::io_service io_service;
auto_ptr<asio::io_service::work> work(
    new asio::io_service::work(io_service));
...
work.reset(); // Allow run() to exit.

Requirements

Header: asio/io_service.hpp

Convenience header: asio.hpp