Provides core I/O functionality. More...

#include <io_context.hpp>

Inheritance diagram for asio::io_context:

Collaboration diagram for asio::io_context:

Classes
class	basic_executor_type
	Executor implementation type used to submit functions to an io_context. More...

struct	initiate_dispatch

struct	initiate_post

class	service
	Base class for all io_context services. More...

class	strand
	Provides serialised handler execution. More...

class	work
	(Deprecated: Use executor_work_guard.) Class to inform the io_context when it has work to do. More...

Public Types
typedef basic_executor_type< std::allocator< void >, 0 >	executor_type
	Executor used to submit functions to an io_context.

typedef std::size_t	count_type
	The type used to count the number of handlers executed by the context.

Public Types inherited from asio::execution_context
enum	fork_event { fork_prepare, fork_parent, fork_child }
	Fork-related event notifications. More...

Public Member Functions
ASIO_DECL	io_context ()
	Constructor.

ASIO_DECL	io_context (int concurrency_hint)
	Constructor. More...

ASIO_DECL	~io_context ()
	Destructor. More...

executor_type	get_executor () ASIO_NOEXCEPT
	Obtains the executor associated with the io_context.

ASIO_DECL count_type	run ()
	Run the io_context object's event processing loop. More...

ASIO_DECL count_type	run (asio::error_code &ec)
	(Deprecated: Use non-error_code overload.) Run the io_context object's event processing loop. More...

ASIO_DECL count_type	run_one ()
	Run the io_context object's event processing loop to execute at most one handler. More...

ASIO_DECL count_type	run_one (asio::error_code &ec)
	(Deprecated: Use non-error_code overlaod.) Run the io_context object's event processing loop to execute at most one handler. More...

ASIO_DECL count_type	poll ()
	Run the io_context object's event processing loop to execute ready handlers. More...

ASIO_DECL count_type	poll (asio::error_code &ec)
	(Deprecated: Use non-error_code overload.) Run the io_context object's event processing loop to execute ready handlers. More...

ASIO_DECL count_type	poll_one ()
	Run the io_context object's event processing loop to execute one ready handler. More...

ASIO_DECL count_type	poll_one (asio::error_code &ec)
	(Deprecated: Use non-error_code overload.) Run the io_context object's event processing loop to execute one ready handler. More...

ASIO_DECL void	stop ()
	Stop the io_context object's event processing loop. More...

ASIO_DECL bool	stopped () const
	Determine whether the io_context object has been stopped. More...

ASIO_DECL void	restart ()
	Restart the io_context in preparation for a subsequent run() invocation. More...

void	reset ()
	(Deprecated: Use restart().) Reset the io_context in preparation for a subsequent run() invocation. More...

template<typename LegacyCompletionHandler >
	dispatch (ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
	(Deprecated: Use asio::dispatch().) Request the io_context to invoke the given handler. More...

template<typename LegacyCompletionHandler >
	post (ASIO_MOVE_ARG(LegacyCompletionHandler) handler)
	(Deprecated: Use asio::post().) Request the io_context to invoke the given handler and return immediately. More...

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

Public Member Functions inherited from asio::execution_context
ASIO_DECL	execution_context ()
	Constructor.

ASIO_DECL	~execution_context ()
	Destructor.

ASIO_DECL void	notify_fork (fork_event event)
	Notify the execution_context of a fork-related event. More...

Friends
template<typename Allocator , unsigned int Bits>
class	basic_executor_type

class	work

template<typename Service >
Service &	use_service (io_context &ioc)

Additional Inherited Members
Protected Member Functions inherited from asio::execution_context
ASIO_DECL void	shutdown ()
	Shuts down all services in the context. More...

ASIO_DECL void	destroy ()
	Destroys all services in the context. More...

Detailed Description

Provides core I/O functionality.

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

The io_context 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 restart() and notify_fork() functions. Calling restart() while there are unfinished run(), run_one(), run_for(), run_until(), poll() or poll_one() calls results in undefined behaviour. The notify_fork() function should not be called while any io_context function, or any function on an I/O object that is associated with the io_context, is being called in another thread.

Concepts:: Dispatcher.

Synchronous and asynchronous operations

Synchronous operations on I/O objects implicitly run the io_context object for an individual operation. The io_context functions run(), run_one(), run_for(), run_until(), poll() or poll_one() must be called for the io_context 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(), run_for(), run_until(), poll() or poll_one() for the io_context.

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(), run_for(), run_until(), 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(), run_for(), run_until(), 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_context object's thread pool without impacting any other threads in the pool.

For example:

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

Submitting arbitrary tasks to the io_context

To submit functions to the io_context, use the asio::dispatch, asio::post or asio::defer free functions.

For example:

 void my_task()
{
  ...
}
...
asio::io_context io_context;
// Submit a function to the io_context.
asio::post(io_context, my_task);
// Submit a lambda object to the io_context.
asio::post(io_context,
    []()
    {
      ...
    });
// Run the io_context until it runs out of work.
io_context.run(); 

Stopping the io_context from running out of work

Some applications may need to prevent an io_context object's run() call from returning when there is no more work to do. For example, the io_context 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 executor that tracks work against the io_context:

 asio::io_context io_context;
auto work = asio::require(io_context.get_executor(),
    asio::execution::outstanding_work.tracked);
... 

If using C++03, which lacks automatic variable type deduction, you may compute the return type of the require call:

 asio::io_context io_context;
typename asio::require_result<
    asio::io_context::executor_type,
    asio::exeution::outstanding_work_t::tracked_t>
  work = asio::require(io_context.get_executor(),
    asio::execution::outstanding_work.tracked);
... 

or store the result in the type-erasing executor wrapper, any_io_executor:

 asio::io_context io_context;
asio::any_io_executor work
  = asio::require(io_context.get_executor(),
      asio::execution::outstanding_work.tracked);
... 

To effect a shutdown, the application will then need to call the io_context object's stop() member function. This will cause the io_context 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, store the work-tracking executor in an any_io_executor object, so that it may be explicitly reset.

 asio::io_context io_context;
asio::any_io_executor work
  = asio::require(io_context.get_executor(),
      asio::execution::outstanding_work.tracked);
...
work = asio::any_io_executor(); // Allow run() to exit. 

Constructor & Destructor Documentation

◆ io_context()

asio::io_context::io_context ( int 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.

◆ ~io_context()

asio::io_context::~io_context ( )

Destructor.

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

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

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

For each service object svc in the io_context set, in reverse order of the beginning of service object lifetime, performs delete static_cast<io_context::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_context function stop() is called to terminate any run() calls as soon as possible. The io_context destructor defined above destroys all handlers, causing all shared_ptr references to all connection objects to be destroyed.

Member Function Documentation

◆ dispatch()

template<typename LegacyCompletionHandler >

asio::io_context::dispatch ( ASIO_MOVE_ARG(LegacyCompletionHandler) handler )

(Deprecated: Use asio::dispatch().) Request the io_context to invoke the given handler.

This function is used to ask the io_context to execute the given handler.

The io_context 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_context 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.

◆ poll() [1/2]

io_context::count_type asio::io_context::poll ( )

Run the io_context object's event processing loop to execute ready handlers.

The poll() function runs handlers that are ready to run, without blocking, until the io_context has been stopped or there are no more ready handlers.

Returns: The number of handlers that were executed.

◆ poll() [2/2]

io_context::count_type asio::io_context::poll ( asio::error_code & ec )

(Deprecated: Use non-error_code overload.) Run the io_context object's event processing loop to execute ready handlers.

The poll() function runs handlers that are ready to run, without blocking, until the io_context 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.

◆ poll_one() [1/2]

io_context::count_type asio::io_context::poll_one ( )

Run the io_context 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.

◆ poll_one() [2/2]

io_context::count_type asio::io_context::poll_one ( asio::error_code & ec )

(Deprecated: Use non-error_code overload.) Run the io_context 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.

◆ post()

template<typename LegacyCompletionHandler >

asio::io_context::post ( ASIO_MOVE_ARG(LegacyCompletionHandler) handler )

(Deprecated: Use asio::post().) Request the io_context to invoke the given handler and return immediately.

This function is used to ask the io_context to execute the given handler, but without allowing the io_context to call the handler from inside this function.

The io_context 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_context 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.

◆ reset()

void asio::io_context::reset ( )

inline

(Deprecated: Use restart().) Reset the io_context 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_context being stopped or running out of work. After a call to restart(), the io_context 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.

◆ restart()

void asio::io_context::restart ( )

Restart the io_context 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_context being stopped or running out of work. After a call to restart(), the io_context 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.

◆ run() [1/2]

io_context::count_type asio::io_context::run ( )

Run the io_context 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_context has been stopped.

Multiple threads may call the run() function to set up a pool of threads from which the io_context may execute handlers. All threads that are waiting in the pool are equivalent and the io_context may choose any one of them to invoke a handler.

A normal exit from the run() function implies that the io_context 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 restart().

Returns: The number of handlers that were executed.

Note: Calling the run() function from a thread that is currently calling one of run(), run_one(), run_for(), run_until(), poll() or poll_one() on the same io_context object may introduce the potential for deadlock. It is the caller's reponsibility to avoid this.

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

◆ run() [2/2]

io_context::count_type asio::io_context::run ( asio::error_code & ec )

(Deprecated: Use non-error_code overload.) Run the io_context 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_context has been stopped.

Multiple threads may call the run() function to set up a pool of threads from which the io_context may execute handlers. All threads that are waiting in the pool are equivalent and the io_context may choose any one of them to invoke a handler.

A normal exit from the run() function implies that the io_context 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 restart().

Parameters

ec	Set to indicate what error occurred, if any.

Returns: The number of handlers that were executed.

Note: Calling the run() function from a thread that is currently calling one of run(), run_one(), run_for(), run_until(), poll() or poll_one() on the same io_context object may introduce the potential for deadlock. It is the caller's reponsibility to avoid this.

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

◆ run_one() [1/2]

io_context::count_type asio::io_context::run_one ( )

Run the io_context 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_context has been stopped.

Returns: The number of handlers that were executed. A zero return value implies that the io_context 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 restart().

Note: Calling the run_one() function from a thread that is currently calling one of run(), run_one(), run_for(), run_until(), poll() or poll_one() on the same io_context object may introduce the potential for deadlock. It is the caller's reponsibility to avoid this.

◆ run_one() [2/2]

io_context::count_type asio::io_context::run_one ( asio::error_code & ec )

(Deprecated: Use non-error_code overlaod.) Run the io_context 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_context has been stopped.

Returns: The number of handlers that were executed. A zero return value implies that the io_context 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 restart().; The number of handlers that were executed.

Note: Calling the run_one() function from a thread that is currently calling one of run(), run_one(), run_for(), run_until(), poll() or poll_one() on the same io_context object may introduce the potential for deadlock. It is the caller's reponsibility to avoid this.

◆ stop()

void asio::io_context::stop ( )

Stop the io_context object's event processing loop.

This function does not block, but instead simply signals the io_context 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 restart() is called.

◆ stopped()

bool asio::io_context::stopped ( ) const

Determine whether the io_context object has been stopped.

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

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

◆ wrap()

template<typename Handler >

detail::wrapped_handler< io_context &, Handler > asio::io_context::wrap ( Handler handler )

inline

(Deprecated: Use asio::bind_executor().) Create a new handler that automatically dispatches the wrapped handler on the io_context.

This function is used to create a new handler function object that, when invoked, will automatically pass the wrapped handler to the io_context object's dispatch function.

Parameters

handler

The handler to be wrapped. The io_context 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_context 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_context.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_context.dispatch(boost::bind(f, a1, ... an));

Friends And Related Function Documentation

◆ use_service

template<typename Service >

Service& use_service ( io_context & ioc )

friend

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_context will create a new instance of the service.

Parameters

ioc	The io_context 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.

Note: This overload is preserved for backwards compatibility with services that inherit from io_context::service.

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

Thirdparty/asio/include/asio/io_context.hpp
Thirdparty/asio/include/asio/impl/io_context.ipp

Classes

Public Types

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ io_context()

◆ ~io_context()

Member Function Documentation

◆ dispatch()

◆ poll() [1/2]

◆ poll() [2/2]

◆ poll_one() [1/2]

◆ poll_one() [2/2]

◆ post()

◆ reset()

◆ restart()

◆ run() [1/2]

◆ run() [2/2]

◆ run_one() [1/2]

◆ run_one() [2/2]

◆ stop()

◆ stopped()

◆ wrap()

Friends And Related Function Documentation

◆ use_service