Provides core I/O functionality.

class io_context :
  public execution_context

Types

Member Functions

Protected Member Functions

Friends

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.

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:

std::experimental::net::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()
{
  ...
}

...

std::experimental::net::io_context io_context;

// Submit a function to the io_context.
std::experimental::net::post(io_context, my_task);

// Submit a lambda object to the io_context.
std::experimental::net::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 std::experimental::net::v1::executor_work_guard<io_context::executor_type>:

std::experimental::net::io_context io_context;
std::experimental::net::executor_work_guard<std::experimental::net::io_context::executor_type>
  = std::experimental::net::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.

std::experimental::net::io_context io_context;
std::experimental::net::executor_work_guard<std::experimental::net::io_context::executor_type>
  = std::experimental::net::make_work_guard(io_context);
...
work.reset(); // Allow run() to exit.