Provides core I/O functionality. More...

#include <io_service.hpp>

Inheritance diagram for boost::asio::io_service:

Collaboration diagram for boost::asio::io_service:

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...

Public Types
enum	fork_event { fork_prepare, fork_parent, fork_child }
	Fork-related event notifications. More...

Public Member Functions
BOOST_ASIO_DECL	io_service ()
	Constructor. More...

BOOST_ASIO_DECL	io_service (std::size_t concurrency_hint)
	Constructor. More...

BOOST_ASIO_DECL	~io_service ()
	Destructor. More...

BOOST_ASIO_DECL std::size_t	run ()
	Run the io_service object's event processing loop. More...

BOOST_ASIO_DECL std::size_t	run (boost::system::error_code &ec)
	Run the io_service object's event processing loop. More...

BOOST_ASIO_DECL std::size_t	run_one ()
	Run the io_service object's event processing loop to execute at most one handler. More...

BOOST_ASIO_DECL std::size_t	run_one (boost::system::error_code &ec)
	Run the io_service object's event processing loop to execute at most one handler. More...

BOOST_ASIO_DECL std::size_t	poll ()
	Run the io_service object's event processing loop to execute ready handlers. More...

BOOST_ASIO_DECL std::size_t	poll (boost::system::error_code &ec)
	Run the io_service object's event processing loop to execute ready handlers. More...

BOOST_ASIO_DECL std::size_t	poll_one ()
	Run the io_service object's event processing loop to execute one ready handler. More...

BOOST_ASIO_DECL std::size_t	poll_one (boost::system::error_code &ec)
	Run the io_service object's event processing loop to execute one ready handler. More...

BOOST_ASIO_DECL void	stop ()
	Stop the io_service object's event processing loop. More...

BOOST_ASIO_DECL bool	stopped () const
	Determine whether the io_service object has been stopped. More...

BOOST_ASIO_DECL void	reset ()
	Reset the io_service in preparation for a subsequent run() invocation. More...

template<typename CompletionHandler >
	dispatch (BOOST_ASIO_MOVE_ARG(CompletionHandler) handler)
	Request the io_service to invoke the given handler. More...

template<typename CompletionHandler >
	post (BOOST_ASIO_MOVE_ARG(CompletionHandler) handler)
	Request the io_service to invoke the given handler and return immediately. More...

template<typename Handler >
detail::wrapped_handler < io_service &, Handler >	wrap (Handler handler)
	Create a new handler that automatically dispatches the wrapped handler on the io_service. More...

BOOST_ASIO_DECL void	notify_fork (boost::asio::io_service::fork_event event)
	Notify the io_service of a fork-related event. More...

Friends
class	work

template<typename Service >
Service &	use_service (io_service &ios)
	Obtain the service object corresponding to the given type. More...

template<typename Service >
void	add_service (io_service &ios, Service *svc)
	Add a service object to the io_service. More...

template<typename Service >
bool	has_service (io_service &ios)
	Determine if an io_service contains a specified service type. More...

Detailed Description

Provides core I/O functionality.

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 specific exceptions of the reset() and notify_fork() functions. Calling reset() 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.

Concepts:: Dispatcher.

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 reset(). This allows the thread to rejoin the io_service object'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 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:

 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 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.

 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. 

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 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 use_service<Service>(), the type argument chooses a service, making available all members of the named type. If Service is not present in an io_service, an object of type 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 has_service<Service>().

Service objects may be explicitly added to an io_service using the function template add_service<Service>(). If the 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.

Member Enumeration Documentation

enum boost::asio::io_service::fork_event

Fork-related event notifications.

Enumerator
fork_prepare	Notify the io_service that the process is about to fork.
fork_parent	Notify the io_service that the process has forked and is the parent.
fork_child	Notify the io_service that the process has forked and is the child.

Constructor & Destructor Documentation

BOOST_ASIO_DECL boost::asio::io_service::io_service ( )

Constructor.

BOOST_ASIO_DECL boost::asio::io_service::io_service ( std::size_t concurrency_hint )

explicit

Constructor.

Construct with a hint about the required level of concurrency.

Parameters

concurrency_hint A suggestion to the implementation on how many threads it should allow to run simultaneously.

BOOST_ASIO_DECL boost::asio::io_service::~io_service ( )

Destructor.

On destruction, the io_service performs the following sequence of operations:

For each service object svc in the io_service set, in reverse order of the beginning of service object lifetime, performs svc->shutdown_service().

Uninvoked handler objects that were scheduled for deferred invocation on the io_service, or any associated strand, are destroyed.

For each service object svc in the io_service set, in reverse order of the beginning of service object lifetime, performs delete static_cast<io_service::service*>(svc).

Note: The destruction sequence described above permits programs to simplify their resource management by using shared_ptr<>. Where an object's lifetime is tied to the lifetime of a connection (or some other sequence of asynchronous operations), a shared_ptr to the object would be bound into the handlers for all asynchronous operations associated with it. This works as follows:

When a single connection ends, all associated asynchronous operations complete. The corresponding handler objects are destroyed, and all shared_ptr references to the objects are destroyed.

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 shared_ptr references to all connection objects to be destroyed.

Member Function Documentation

template<typename CompletionHandler >

boost::asio::io_service::dispatch ( BOOST_ASIO_MOVE_ARG(CompletionHandler) 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.

Parameters

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();

Note: This function throws an exception only if:

the handler's asio_handler_allocate function; or

the handler's copy constructor

throws an exception.

BOOST_ASIO_DECL void boost::asio::io_service::notify_fork ( boost::asio::io_service::fork_event event )

Notify the io_service of a fork-related event.

This function is used to inform the io_service that the process is about to fork, or has just forked. This allows the io_service, and the services it contains, to perform any necessary housekeeping to ensure correct operation following a fork.

This function must not be called while any other io_service function, or any function on an I/O object associated with the io_service, is being called in another thread. It is, however, safe to call this function from within a completion handler, provided no other thread is accessing the io_service.

Parameters

event A fork-related event.

Exceptions

boost::system::system_error Thrown on failure. If the notification fails the io_service object should no longer be used and should be destroyed.

Example: The following code illustrates how to incorporate the notify_fork() function:
my_io_service.notify_fork(boost::asio::io_service::fork_prepare);

if (fork() == 0)

{

// This is the child process.

my_io_service.notify_fork(boost::asio::io_service::fork_child);

}

else

{

// This is the parent process.

my_io_service.notify_fork(boost::asio::io_service::fork_parent);

}

Note: For each service object svc in the io_service set, performs svc->fork_service();. When processing the fork_prepare event, services are visited in reverse order of the beginning of service object lifetime. Otherwise, services are visited in order of the beginning of service object lifetime.

BOOST_ASIO_DECL std::size_t boost::asio::io_service::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.

Returns: The number of handlers that were executed.

Exceptions

boost::system::system_error Thrown on failure.

BOOST_ASIO_DECL std::size_t boost::asio::io_service::poll ( 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.

Parameters

ec	Set to indicate what error occurred, if any.

Returns: The number of handlers that were executed.

BOOST_ASIO_DECL std::size_t boost::asio::io_service::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.

Returns: The number of handlers that were executed.

Exceptions

boost::system::system_error Thrown on failure.

BOOST_ASIO_DECL std::size_t boost::asio::io_service::poll_one ( 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.

Parameters

ec	Set to indicate what error occurred, if any.

Returns: The number of handlers that were executed.

template<typename CompletionHandler >

boost::asio::io_service::post ( BOOST_ASIO_MOVE_ARG(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.

Parameters

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();

Note: This function throws an exception only if:

the handler's asio_handler_allocate function; or

the handler's copy constructor

throws an exception.

Referenced by boost::asio::basic_socket< Protocol, StreamSocketService >::BOOST_ASIO_MOVE_ARG().

BOOST_ASIO_DECL void boost::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. After a call to reset(), the io_service object's stopped() function will return false.

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 std::size_t boost::asio::io_service::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.

A normal exit from the run() function implies that the io_service object is stopped (the stopped() function returns true). Subsequent calls to run(), run_one(), poll() or poll_one() will return immediately unless there is a prior call to reset().

Returns: The number of handlers that were executed.

Exceptions

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 boost::asio::io_service::run ( boost::system::error_code & ec )

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.

A normal exit from the run() function implies that the io_service object is stopped (the stopped() function returns true). Subsequent calls to run(), run_one(), poll() or poll_one() will return immediately unless there is a prior call to reset().

Parameters

ec	Set to indicate what error occurred, if any.

Returns: 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 boost::asio::io_service::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.

Returns: The number of handlers that were executed. A zero return value implies that the io_service object is stopped (the stopped() function returns true). Subsequent calls to run(), run_one(), poll() or poll_one() will return immediately unless there is a prior call to reset().

Exceptions

boost::system::system_error Thrown on failure.

BOOST_ASIO_DECL std::size_t boost::asio::io_service::run_one ( 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.

Returns: The number of handlers that were executed. A zero return value implies that the io_service object is stopped (the stopped() function returns true). Subsequent calls to run(), run_one(), poll() or poll_one() will return immediately unless there is a prior call to reset().; The number of handlers that were executed.

BOOST_ASIO_DECL void boost::asio::io_service::stop ( )

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 bool boost::asio::io_service::stopped ( ) const

Determine whether the io_service object has been stopped.

This function is used to determine whether an io_service object has been stopped, either through an explicit call to stop(), or due to running out of work. When an io_service object is stopped, calls to run(), run_one(), poll() or poll_one() will return immediately without invoking any handlers.

Returns: true if the io_service object is stopped, otherwise false.

template<typename Handler >

detail::wrapped_handler<io_service&, Handler> boost::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 object's dispatch function.

Parameters

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);

Returns: 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:
R f(A1 a1, ... An an);

If this function object is passed to the wrap function like so:
io_service.wrap(f);

then the return value is a function object with the signature
void g(A1 a1, ... An an);

that, when invoked, executes code equivalent to:
io_service.dispatch(boost::bind(f, a1, ... an));

Friends And Related Function Documentation

template<typename 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.

Parameters

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)

Exceptions

boost::asio::service_already_exists	Thrown if a service of the given type is already present in the io_service.
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 >

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.

Parameters

ios	The io_service object that owns the service.

Returns: A boolean indicating whether the io_service contains the service.

template<typename Service >

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.

Parameters

ios	The io_service object that owns the service.

Returns: The service interface implementing the specified service type. Ownership of the service interface is not transferred to the caller.

friend class work

friend

The documentation for this class was generated from the following file:

boost_1_57_0/boost/asio/io_service.hpp

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation