1[/
2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
3 /
4 / Distributed under the Boost Software License, Version 1.0. (See accompanying
5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 /]
7
8[section:concurrency_hint Concurrency Hints]
9
10The [link boost_asio.reference.io_context.io_context `io_context` constructor]
11allows programs to specify a concurrency hint. This is a suggestion to the
12`io_context` implementation as to the number of active threads that should be
13used for running completion handlers.
14
15When the Windows I/O completion port backend is in use, this value is passed
16to [^CreateIoCompletionPort].
17
18When a reactor-based backend is used, the implementation recognises the
19following special concurrency hint values:
20
21[table
22  [[Value][Description]]
23  [
24    [`1`]
25    [
26      The implementation assumes that the `io_context` will be run from a
27      single thread, and applies several optimisations based on this
28      assumption.
29
30      For example, when a handler is posted from within another handler, the
31      new handler is added to a fast thread-local queue (with the consequence
32      that the new handler is held back until the currently executing handler
33      finishes).
34    ]
35  ]
36  [
37    [`BOOST_ASIO_CONCURRENCY_HINT_UNSAFE`]
38    [
39      This special concurrency hint disables locking in both the scheduler and
40      reactor I/O. This hint has the following restrictions:
41
42      [mdash] Care must be taken to ensure that all operations on the
43      `io_context` and any of its associated I/O objects (such as sockets and
44      timers) occur in only one thread at a time.
45
46      [mdash] Asynchronous resolve operations fail with `operation_not_supported`.
47
48      [mdash] If a `signal_set` is used with the `io_context`, `signal_set`
49      objects cannot be used with any other io_context in the program.
50    ]
51  ]
52  [
53    [`BOOST_ASIO_CONCURRENCY_HINT_UNSAFE_IO`]
54    [
55      This special concurrency hint disables locking in the reactor I/O. This
56      hint has the following restrictions:
57
58      [mdash] Care must be taken to ensure that run functions on the
59      `io_context`, and all operations on the context's associated I/O objects
60      (such as sockets and timers), occur in only one thread at a time.
61    ]
62  ]
63  [
64    [`BOOST_ASIO_CONCURRENCY_HINT_SAFE`]
65    [
66      The default. The `io_context` provides full thread safety, and distinct
67      I/O objects may be used from any thread.
68    ]
69  ]
70]
71
72[teletype]
73The concurrency hint used by default-constructed `io_context` objects can be
74overridden at compile time by defining the `BOOST_ASIO_CONCURRENCY_HINT_DEFAULT`
75macro. For example, specifying
76
77  -DBOOST_ASIO_CONCURRENCY_HINT_DEFAULT=1
78
79on the compiler command line means that a concurrency hint of `1` is used for
80all default-constructed `io_context` objects in the program. Similarly, the
81concurrency hint used by `io_context` objects constructed with `1` can be
82overridden by defining `BOOST_ASIO_CONCURRENCY_HINT_1`. For example, passing
83
84  -DBOOST_ASIO_CONCURRENCY_HINT_1=BOOST_ASIO_CONCURRENCY_HINT_UNSAFE
85
86to the compiler will disable thread safety for all of these objects.
87
88[endsect]
89