Concurrency Hints

The io_context constructor allows programs to specify a concurrency hint. This is a suggestion to the io_context implementation as to the number of active threads that should be used for running completion handlers.

When the Windows I/O completion port backend is in use, this value is passed to CreateIoCompletionPort.

When a reactor-based backend is used, the implementation recognises the following special concurrency hint values:

Value	Description
`1`	The implementation assumes that the `io_context` will be run from a single thread, and applies several optimisations based on this assumption. For example, when a handler is posted from within another handler, the new handler is added to a fast thread-local queue (with the consequence that the new handler is held back until the currently executing handler finishes). The `io_context` still provides full thread safety, and distinct I/O objects may be used from any thread.
`ASIO_CONCURRENCY_HINT_UNSAFE`	This special concurrency hint disables locking in both the scheduler and reactor I/O. This hint has the following restrictions: — Care must be taken to ensure that all operations on the `io_context` and any of its associated I/O objects (such as sockets and timers) occur in only one thread at a time. — Asynchronous resolve operations fail with `operation_not_supported`. — If a `signal_set` is used with the `io_context`, `signal_set` objects cannot be used with any other io_context in the program.
`ASIO_CONCURRENCY_HINT_UNSAFE_IO`	This special concurrency hint disables locking in the reactor I/O. This hint has the following restrictions: — Care must be taken to ensure that the run functions on the `io_context` (i.e. `run`, `run_for`, `run_until`, `run_one`, `run_one_for`, `run_one_until`, `poll`, and `poll_one`), and all operations on the context's associated I/O objects (such as sockets and timers), occur in only one thread at a time.
`ASIO_CONCURRENCY_HINT_SAFE`	The default. The `io_context` provides full thread safety, and distinct I/O objects may be used from any thread.

The concurrency hint used by default-constructed io_context objects can be overridden at compile time by defining the ASIO_CONCURRENCY_HINT_DEFAULT macro. For example, specifying

-DASIO_CONCURRENCY_HINT_DEFAULT=1

on the compiler command line means that a concurrency hint of 1 is used for all default-constructed io_context objects in the program. Similarly, the concurrency hint used by io_context objects constructed with 1 can be overridden by defining ASIO_CONCURRENCY_HINT_1. For example, passing

-DASIO_CONCURRENCY_HINT_1=ASIO_CONCURRENCY_HINT_UNSAFE

to the compiler will disable thread safety for all of these objects.