diff options
Diffstat (limited to '3rdparty/asio/src/doc/overview/threads.qbk')
-rw-r--r-- | 3rdparty/asio/src/doc/overview/threads.qbk | 66 |
1 files changed, 66 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/threads.qbk b/3rdparty/asio/src/doc/overview/threads.qbk new file mode 100644 index 00000000000..b5239d9828e --- /dev/null +++ b/3rdparty/asio/src/doc/overview/threads.qbk @@ -0,0 +1,66 @@ +[/ + / Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:threads Threads and Asio] + +[heading Thread Safety] + +In general, it is safe to make concurrent use of distinct objects, but unsafe +to make concurrent use of a single object. However, types such as `io_context` +provide a stronger guarantee that it is safe to use a single object +concurrently. + +[heading Thread Pools] + +Multiple threads may call `io_context::run()` to set up a pool of threads from +which completion handlers may be invoked. This approach may also be used with +`io_context::post()` to use a means to perform any computational tasks across a +thread pool. + +Note that all threads that have joined an `io_context`'s pool are considered +equivalent, and the `io_context` may distribute work across them in an +arbitrary fashion. + +[heading Internal Threads] + +The implementation of this library for a particular platform may make use of +one or more internal threads to emulate asynchronicity. As far as possible, +these threads must be invisible to the library user. In particular, the threads: + +* must not call the user's code directly; and + +* must block all signals. + +This approach is complemented by the following guarantee: + +* Asynchronous completion handlers will only be called from threads that are + currently calling `io_context::run()`. + +Consequently, it is the library user's responsibility to create and manage all +threads to which the notifications will be delivered. + +The reasons for this approach include: + +* By only calling `io_context::run()` from a single thread, the user's code can + avoid the development complexity associated with synchronisation. For + example, a library user can implement scalable servers that are + single-threaded (from the user's point of view). + +* A library user may need to perform initialisation in a thread shortly after + the thread starts and before any other application code is executed. For + example, users of Microsoft's COM must call `CoInitializeEx` before any other + COM operations can be called from that thread. + +* The library interface is decoupled from interfaces for thread creation and + management, and permits implementations on platforms where threads are not + available. + +[heading See Also] + +[link asio.reference.io_context io_context]. + +[endsect] |