Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

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.

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

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

BOOST_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 BOOST_ASIO_CONCURRENCY_HINT_DEFAULT macro. For example, specifying

-DBOOST_ASIO_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 BOOST_ASIO_CONCURRENCY_HINT_1. For example, passing

-DBOOST_ASIO_CONCURRENCY_HINT_1=BOOST_ASIO_CONCURRENCY_HINT_UNSAFE

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


PrevUpHomeNext