...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Provides core I/O functionality.
class io_context : public execution_context
Name |
Description |
---|---|
Executor implementation type used to submit functions to an io_context. |
|
Base class for all io_context services. |
|
Provides serialised handler execution. |
|
(Deprecated: Use executor_work_guard.) Class to inform the io_context when it has work to do. |
|
The type used to count the number of handlers executed by the context. |
|
Executor used to submit functions to an io_context. |
|
Fork-related event notifications. |
Name |
Description |
---|---|
(Deprecated: Use boost::asio::dispatch().) Request the io_context to invoke the given handler. |
|
Obtains the executor associated with the io_context. |
|
io_context [constructor] |
Constructor. |
Notify the execution_context of a fork-related event. |
|
Run the io_context object's event processing loop to execute ready
handlers. |
|
Run the io_context object's event processing loop to execute one
ready handler. |
|
(Deprecated: Use boost::asio::post().) Request the io_context to invoke the given handler and return immediately. |
|
(Deprecated: Use restart().) Reset the io_context in preparation for a subsequent run() invocation. |
|
Restart the io_context in preparation for a subsequent run() invocation. |
|
Run the io_context object's event processing loop. |
|
Run the io_context object's event processing loop for a specified duration. |
|
Run the io_context object's event processing loop to execute at
most one handler. |
|
Run the io_context object's event processing loop for a specified duration to execute at most one handler. |
|
Run the io_context object's event processing loop until a specified time to execute at most one handler. |
|
Run the io_context object's event processing loop until a specified time. |
|
Stop the io_context object's event processing loop. |
|
Determine whether the io_context object has been stopped. |
|
(Deprecated: Use boost::asio::bind_executor().) Create a new handler that automatically dispatches the wrapped handler on the io_context. |
|
~io_context [destructor] |
Destructor. |
Name |
Description |
---|---|
Destroys all services in the context. |
|
Shuts down all services in the context. |
Name |
Description |
---|---|
(Deprecated: Use make_service().) Add a service object to the execution_context. |
|
Determine if an execution_context contains a specified service type. |
|
Creates a service object and adds it to the execution_context. |
|
|
The io_context
class provides the core I/O functionality for users of the asynchronous I/O
objects, including:
boost::asio::ip::tcp::socket
boost::asio::ip::tcp::acceptor
boost::asio::ip::udp::socket
deadline_timer
.
The io_context
class also includes facilities intended for developers of custom asynchronous
services.
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.
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
.
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:
boost::asio::io_context io_context; ... for (;;) { try { io_context.run(); break; // run() exited normally } catch (my_exception& e) { // Deal with exception as appropriate. } }
To submit functions to the io_context
,
use the dispatch
, post
or
defer
free
functions.
For example:
void my_task() { ... } ... boost::asio::io_context io_context; // Submit a function to the io_context. boost::asio::post(io_context, my_task); // Submit a lambda object to the io_context. boost::asio::post(io_context, []() { ... }); // Run the io_context until it runs out of work. io_context.run();
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
:
boost::asio::io_context io_context; auto work = boost::asio::require(io_context.get_executor(), boost::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:
boost::asio::io_context io_context; typename boost::asio::require_result< boost::asio::io_context::executor_type, boost::asio::exeution::outstanding_work_t::tracked_t> work = boost::asio::require(io_context.get_executor(), boost::asio::execution::outstanding_work.tracked); ...
or store the result in the type-erasing executor wrapper, any_io_executor
:
boost::asio::io_context io_context; boost::asio::any_io_executor work = boost::asio::require(io_context.get_executor(), boost::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.
boost::asio::io_context io_context; boost::asio::any_io_executor work = boost::asio::require(io_context.get_executor(), boost::asio::execution::outstanding_work.tracked); ... work = boost::asio::any_io_executor(); // Allow run() to exit.
Header: boost/asio/io_context.hpp
Convenience header: boost/asio.hpp