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:threads Threads and Boost.Asio] 9 10[heading Thread Safety] 11 12In general, it is safe to make concurrent use of distinct objects, but unsafe 13to make concurrent use of a single object. However, types such as `io_context` 14provide a stronger guarantee that it is safe to use a single object 15concurrently. 16 17[heading Thread Pools] 18 19Multiple threads may call `io_context::run()` to set up a pool of threads from 20which completion handlers may be invoked. This approach may also be used with 21`post()` as a means to perform arbitrary computational tasks across a thread 22pool. 23 24Note that all threads that have joined an `io_context`'s pool are considered 25equivalent, and the `io_context` may distribute work across them in an 26arbitrary fashion. 27 28[heading Internal Threads] 29 30The implementation of this library for a particular platform may make use of 31one or more internal threads to emulate asynchronicity. As far as possible, 32these threads must be invisible to the library user. In particular, the threads: 33 34* must not call the user's code directly; and 35 36* must block all signals. 37 38This approach is complemented by the following guarantee: 39 40* Asynchronous completion handlers will only be called from threads that are 41 currently calling `io_context::run()`. 42 43Consequently, it is the library user's responsibility to create and manage all 44threads to which the notifications will be delivered. 45 46The reasons for this approach include: 47 48* By only calling `io_context::run()` from a single thread, the user's code can 49 avoid the development complexity associated with synchronisation. For 50 example, a library user can implement scalable servers that are 51 single-threaded (from the user's point of view). 52 53* A library user may need to perform initialisation in a thread shortly after 54 the thread starts and before any other application code is executed. For 55 example, users of Microsoft's COM must call `CoInitializeEx` before any other 56 COM operations can be called from that thread. 57 58* The library interface is decoupled from interfaces for thread creation and 59 management, and permits implementations on platforms where threads are not 60 available. 61 62[heading See Also] 63 64[link boost_asio.reference.io_context io_context], 65[link boost_asio.reference.post post]. 66 67[endsect] 68