Provides core I/O functionality. More...

#include <io_service.hpp>

Inheritance diagram for 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 Member Functions
template<typename CompletionHandler >
void	dispatch (CompletionHandler handler)
	Request the io_service to invoke the given handler.
	io_service ()
	Constructor.
	io_service (std::size_t concurrency_hint)
	Constructor.
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.
template<typename CompletionHandler >
void	post (CompletionHandler handler)
	Request the io_service to invoke the given handler and return immediately.
void	reset ()
	Reset the io_service in preparation for a subsequent run() invocation.
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.
void	stop ()
	Stop the io_service's event processing loop.
template<typename Handler >
unspecified detail::wrapped_handler < io_service &, Handler >	wrap (Handler handler)
	~io_service ()
	Destructor.
Private Types
typedef detail::win_iocp_io_service	impl_type
typedef detail::task_io_service < detail::epoll_reactor< false > >	impl_type
typedef detail::task_io_service < detail::kqueue_reactor < false > >	impl_type
typedef detail::task_io_service < detail::dev_poll_reactor < false > >	impl_type
typedef detail::task_io_service < detail::select_reactor < false > >	impl_type
Private Attributes
impl_type &	impl_
detail::winsock_init	init_
detail::signal_init	init_
asio::detail::service_registry *	service_registry_
Friends
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.
template<typename Service >
Service &	use_service (io_service &ios)
	Obtain the service object corresponding to the given type.
class	work

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 exception that calling reset() while there are unfinished run() calls results in undefined behaviour.

Concepts:: Dispatcher.

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 asio::io_service::run(), asio::io_service::run_one(), asio::io_service::poll() or 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 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.
   }
 }

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 asio::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'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.

Definition at line 130 of file io_service.hpp.

Member Typedef Documentation

typedef detail::win_iocp_io_service asio::io_service::impl_type [private]

Definition at line 136 of file io_service.hpp.

typedef detail::task_io_service<detail::epoll_reactor<false> > asio::io_service::impl_type [private]

Definition at line 138 of file io_service.hpp.

typedef detail::task_io_service<detail::kqueue_reactor<false> > asio::io_service::impl_type [private]

Definition at line 140 of file io_service.hpp.

typedef detail::task_io_service<detail::dev_poll_reactor<false> > asio::io_service::impl_type [private]

Definition at line 142 of file io_service.hpp.

typedef detail::task_io_service<detail::select_reactor<false> > asio::io_service::impl_type [private]

Definition at line 144 of file io_service.hpp.

Constructor & Destructor Documentation

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.

Parameters:

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

asio::io_service::~io_service ( )

Destructor.

Member Function Documentation

template<typename CompletionHandler >

void asio::io_service::dispatch ( 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();

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.

Returns:: The number of handlers that were executed.

Exceptions:

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.

Parameters:

ec	Set to indicate what error occurred, if any.

Returns:: The number of handlers that were executed.

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.

Returns:: The number of handlers that were executed.

Exceptions:

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.

Parameters:

ec	Set to indicate what error occurred, if any.

Returns:: The number of handlers that were executed.

template<typename CompletionHandler >

void asio::io_service::post ( 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();

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.

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

Returns:: The number of handlers that were executed.

Exceptions:

asio::system_error Thrown on failure.

Note:: The poll() function may also be used to dispatch ready handlers, but without blocking.

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

Parameters:

ec	Set to indicate what error occurred, if any.

Returns:: The number of handlers that were executed.

Note:: The poll() function may also be used to dispatch ready handlers, but without blocking.

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.

Returns:: The number of handlers that were executed.

Exceptions:

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.

Parameters:

ec	Set to indicate what error occurred, if any.

Returns:: The number of handlers that were executed.

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.

template<typename Handler >

unspecified detail::wrapped_handler<io_service&, Handler> 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.

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'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:

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.

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]

Definition at line 148 of file io_service.hpp.

Member Data Documentation

impl_type& asio::io_service::impl_ [private]

Definition at line 425 of file io_service.hpp.

detail::winsock_init asio::io_service::init_ [private]

Definition at line 415 of file io_service.hpp.

detail::signal_init asio::io_service::init_ [private]

Definition at line 418 of file io_service.hpp.

asio::detail::service_registry* asio::io_service::service_registry_ [private]

Definition at line 422 of file io_service.hpp.

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

io_service.hpp

Classes

Public Member Functions

Private Types

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation