summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/requirements/Executor.qbk
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/asio/src/doc/requirements/Executor.qbk')
-rw-r--r--3rdparty/asio/src/doc/requirements/Executor.qbk141
1 files changed, 141 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/requirements/Executor.qbk b/3rdparty/asio/src/doc/requirements/Executor.qbk
new file mode 100644
index 00000000000..07548605730
--- /dev/null
+++ b/3rdparty/asio/src/doc/requirements/Executor.qbk
@@ -0,0 +1,141 @@
+[/
+ / 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:Executor1 Executor requirements]
+
+The library describes a standard set of requirements for ['executors]. A type
+meeting the `Executor` requirements embodies a set of rules for determining how
+submitted function objects are to be executed.
+
+A type `X` meets the `Executor` requirements if it satisfies the requirements of
+`CopyConstructible` (C++Std [copyconstructible]) and `Destructible` (C++Std
+[destructible]), as well as the additional requirements listed below.
+
+No constructor, comparison operator, copy operation, move operation, swap
+operation, or member functions `context`, `on_work_started`, and
+`on_work_finished` on these types shall exit via an exception.
+
+The executor copy constructor, comparison operators, and other member functions
+defined in these requirements shall not introduce data races as a result of
+concurrent calls to those functions from different threads.
+
+Let `ctx` be the execution context returned by the executor's `context()`
+member function. An executor becomes ['invalid] when the first call to
+`ctx.shutdown()` returns. The effect of calling `on_work_started`,
+`on_work_finished`, `dispatch`, `post`, or `defer` on an invalid executor is
+undefined. [inline_note The copy constructor, comparison operators, and
+`context()` member function continue to remain valid until `ctx` is destroyed.]
+
+In the table below, `x1` and `x2` denote (possibly const) values of type `X`,
+`mx1` denotes an xvalue of type `X`, `f` denotes a `MoveConstructible` (C++Std
+[moveconstructible]) function object callable with zero arguments, `a` denotes
+a (possibly const) value of type `A` meeting the `Allocator` requirements
+(C++Std [allocator.requirements]), and `u` denotes an identifier.
+
+[table Executor requirements
+ [[expression] [type] [assertion/note\npre/post-conditions]]
+ [
+ [`X u(x1);`]
+ []
+ [Shall not exit via an exception.\n
+ \n
+ post: `u == x1` and
+ `std::addressof(u.context()) == std::addressof(x1.context()).`]
+ ]
+ [
+ [`X u(mx1);`]
+ []
+ [Shall not exit via an exception.\n
+ \n
+ post: `u` equals the prior value of `mx1` and
+ `std::addressof(u.context())` equals the prior value of
+ `std::addressof(mx1.context())`.]
+ ]
+ [
+ [`x1 == x2`]
+ [`bool`]
+ [ Returns `true` only if `x1` and `x2` can be interchanged with identical
+ effects in any of the expressions defined in these type requirements.
+ [inline_note Returning `false` does not necessarily imply that the effects
+ are not identical.]\n
+ \n
+ `operator==` shall be reflexive, symmetric, and transitive, and shall not
+ exit via an exception.]
+ ]
+ [
+ [`x1 != x2`]
+ [`bool`]
+ [Same as `!(x1 == x2)`.]
+ ]
+ [
+ [`x1.context()`]
+ [`execution_context&`, or `E&` where `E` is a type that satifisfies the
+ [link asio.reference.ExecutionContext `ExecutionContext`] requirements.]
+ [Shall not exit via an exception.\n
+ \n
+ The comparison operators and member functions defined in these
+ requirements shall not alter the reference returned by this function.]
+ ]
+ [
+ [`x1.on_work_started()`]
+ []
+ [Shall not exit via an exception.]
+ ]
+ [
+ [`x1.on_work_finished()`]
+ []
+ [Shall not exit via an exception.\n
+ \n
+ Precondition: A preceding call `x2.on_work_started()` where `x1 == x2`.]
+ ]
+ [
+ [`x1.dispatch(std::move(f),a)`]
+ []
+ [Effects: Creates an object `f1` initialized with
+ [^['DECAY_COPY]]`(forward<Func>(f))` (C++Std \[thread.decaycopy\]) in the
+ current thread of execution . Calls `f1()` at most once. The executor may
+ block forward progress of the caller until `f1()` finishes execution.\n
+ \n
+ Executor implementations should use the supplied allocator to allocate any
+ memory required to store the function object. Prior to invoking the
+ function object, the executor shall deallocate any memory allocated.
+ [inline_note Executors defined in this Technical Specification always use
+ the supplied allocator unless otherwise specified.]\n
+ \n
+ Synchronization: The invocation of `dispatch` synchronizes with (C++Std
+ \[intro.multithread\]) the invocation of `f1`.]
+ ]
+ [
+ [`x1.post(std::move(f),a)`\n
+ `x1.defer(std::move(f),a)`]
+ []
+ [Effects: Creates an object `f1` initialized with
+ [^['DECAY_COPY]]`(forward<Func>(f))` in the current thread of execution.
+ Calls `f1()` at most once. The executor shall not block forward progress
+ of the caller pending completion of `f1()`.\n
+ \n
+ Executor implementations should use the supplied allocator to allocate any
+ memory required to store the function object. Prior to invoking the
+ function object, the executor shall deallocate any memory allocated.
+ [inline_note Executors defined in this Technical Specification always use
+ the supplied allocator unless otherwise specified.]\n
+ \n
+ Synchronization: The invocation of `post` or `defer` synchronizes with
+ (C++Std \[intro.multithread\]) the invocation of `f1`.\n
+ \n
+ [inline_note Although the requirements placed on `defer` are identical to
+ `post`, the use of `post` conveys a preference that the caller ['does not]
+ block the first step of [^f1]'s progress, whereas `defer` conveys a
+ preference that the caller ['does] block the first step of [^f1]. One use
+ of `defer` is to convey the intention of the caller that [^f1] is a
+ continuation of the current call context. The executor may use this
+ information to optimize or otherwise adjust the way in which `f1` is
+ invoked.]]
+ ]
+]
+
+[endsect]