| Home | Libraries | People | FAQ | More

### io_context

Provides core I/O functionality.

    class io_context :
      public execution_context

##### Types

Name | Description
--- | ---
executor_type | Executor used to submit functions to an io_context.
service | Base class for all io_context services.
strand | Provides serialised handler execution.
work | (Deprecated: Use executor_work_guard.) Class to inform the io_context when it has work to do.
count_type | The type used to count the number of handlers executed by the context.
fork_event | Fork-related event notifications.

##### Member Functions

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

##### Protected Member Functions

Name | Description
--- | ---
destroy | Destroys all services in the context.
shutdown | 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_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.

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

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

    boost::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 `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();

##### 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 object of type boost::asio::executor_work_guard<io_context::executor_type>:

    boost::asio::io_context io_context;
    boost::asio::executor_work_guard<boost::asio::io_context::executor_type>
      = boost::asio::make_work_guard(io_context);
    ...

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, the work object may be explicitly reset.

    boost::asio::io_context io_context;
    boost::asio::executor_work_guard<boost::asio::io_context::executor_type>
      = boost::asio::make_work_guard(io_context);
    ...
    work.reset(); // Allow run() to exit.

##### Requirements

Header: `boost/asio/io_context.hpp`

Convenience header: `boost/asio.hpp`