123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141 |
- [/
- / Copyright (c) 2003-2019 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 boost_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]
|