[atomics.types.operations] - C++14 → C++17

Files changed (1) hide show

tmp/tmpeam3ahs9/{from.md → to.md} +140 -261

tmp/tmpeam3ahs9/{from.md → to.md} RENAMED Viewed

@@ -1,361 +1,240 @@
-## Operations on atomic types <a id="atomics.types.operations">[[atomics.types.operations]]</a>
-### General operations on atomic types <a id="atomics.types.operations.general">[[atomics.types.operations.general]]</a>
-The implementation shall provide the functions and function templates
-identified as “general operations on atomic types” in  [[atomics.syn]].
-In the declarations of these functions and function templates, the name
-*atomic-type* refers to either `atomic<T>` or to a named base class for
-`T` from Table  [[tab:atomics.integral]] or inferred from Table
-[[tab:atomics.typedefs]].
-### Templated operations on atomic types <a id="atomics.types.operations.templ">[[atomics.types.operations.templ]]</a>
-The implementation shall declare but not define the function templates
-identified as “templated operations on atomic types” in
-[[atomics.syn]].
-### Arithmetic operations on atomic types <a id="atomics.types.operations.arith">[[atomics.types.operations.arith]]</a>
-The implementation shall provide the functions and function template
-specializations identified as “arithmetic operations on atomic types”
-in  [[atomics.syn]].
-In the declarations of these functions and function template
-specializations, the name *integral* refers to an integral type and the
-name *atomic-integral* refers to either `atomic<integral>` or to a named
-base class for `integral` from Table  [[tab:atomics.integral]] or
-inferred from Table  [[tab:atomics.typedefs]].
-### Operations on atomic pointer types <a id="atomics.types.operations.pointer">[[atomics.types.operations.pointer]]</a>
-The implementation shall provide the function template specializations
-identified as “partial specializations for pointers” in
-[[atomics.syn]].
-### Requirements for operations on atomic types <a id="atomics.types.operations.req">[[atomics.types.operations.req]]</a>
-There are only a few kinds of operations on atomic types, though there
-are many instances on those kinds. This section specifies each general
-kind. The specific instances are defined in [[atomics.types.generic]],
-[[atomics.types.operations.general]],
-[[atomics.types.operations.arith]], and
-[[atomics.types.operations.pointer]].
-In the following operation definitions:
-- an *A* refers to one of the atomic types.
-- a *C* refers to its corresponding non-atomic type.
-- an *M* refers to type of the other argument for arithmetic operations.
-  For integral atomic types, *M* is *C*. For atomic address types, *M*
-  is `std::ptrdiff_t`.
-- the non-member functions not ending in `_explicit` have the semantics
-  of their corresponding `_explicit` functions with `memory_order`
-  arguments of `memory_order_seq_cst`.
-Many operations are volatile-qualified. The “volatile as device
-register” semantics have not changed in the standard. This qualification
-means that volatility is preserved when applying these operations to
-volatile objects. It does not mean that operations on non-volatile
-objects become volatile. Thus, volatile qualified operations on
-non-volatile objects may be merged under some conditions.
 ``` cpp
-A::A() noexcept = default;
 ```
-*Effects:* leaves the atomic object in an uninitialized state. These
-semantics ensure compatibility with C.
 ``` cpp
-constexpr A::A(C desired) noexcept;
 ```
 *Effects:* Initializes the object with the value `desired`.
-Initialization is not an atomic operation ([[intro.multithread]]). it
-is possible to have an access to an atomic object `A` race with its
-construction, for example by communicating the address of the
-just-constructed object `A` to another thread via `memory_order_relaxed`
-operations on a suitable atomic pointer variable, and then immediately
-accessing `A` in the receiving thread. This results in undefined
-behavior.
 ``` cpp
 #define ATOMIC_VAR_INIT(value) see below
 ```
 The macro expands to a token sequence suitable for constant
 initialization of an atomic variable of static storage duration of a
-type that is initialization-compatible with *value*. This operation may
-need to initialize locks. Concurrent access to the variable being
-initialized, even via an atomic operation, constitutes a data race.
 ``` cpp
 atomic<int> v = ATOMIC_VAR_INIT(5);
 ```
 ``` cpp
-bool atomic_is_lock_free(const volatile A* object) noexcept;
-bool atomic_is_lock_free(const A* object) noexcept;
-bool A::is_lock_free() const volatile noexcept;
-bool A::is_lock_free() const noexcept;
 ```
-*Returns:* True if the object’s operations are lock-free, false
 otherwise.
-``` cpp
-void atomic_init(volatile A* object, C desired) noexcept;
-void atomic_init(A* object, C desired) noexcept;
-```
-*Effects:* Non-atomically initializes `*object` with value `desired`.
-This function shall only be applied to objects that have been default
-constructed, and then only once. These semantics ensure compatibility
-with C. Concurrent access from another thread, even via an atomic
-operation, constitutes a data race.
 ``` cpp
-void atomic_store(volatile A* object, C desired) noexcept;
-void atomic_store(A* object, C desired) noexcept;
-void atomic_store_explicit(volatile A* object, C desired, memory_order order) noexcept;
-void atomic_store_explicit(A* object, C desired, memory_order order) noexcept;
-void A::store(C desired, memory_order order = memory_order_seq_cst) volatile noexcept;
-void A::store(C desired, memory_order order = memory_order_seq_cst) noexcept;
 ```
 *Requires:* The `order` argument shall not be `memory_order_consume`,
 `memory_order_acquire`, nor `memory_order_acq_rel`.
-*Effects:* Atomically replaces the value pointed to by `object` or by
-`this` with the value of `desired`. Memory is affected according to the
-value of `order`.
 ``` cpp
-C A::operator=(C desired) volatile noexcept;
-C A::operator=(C desired) noexcept;
 ```
-*Effects:* `store(desired)`
-*Returns:* `desired`
 ``` cpp
-C atomic_load(const volatile A* object) noexcept;
-C atomic_load(const A* object) noexcept;
-C atomic_load_explicit(const volatile A* object, memory_order) noexcept;
-C atomic_load_explicit(const A* object, memory_order) noexcept;
-C A::load(memory_order order = memory_order_seq_cst) const volatile noexcept;
-C A::load(memory_order order = memory_order_seq_cst) const noexcept;
 ```
 *Requires:* The `order` argument shall not be `memory_order_release` nor
 `memory_order_acq_rel`.
 *Effects:* Memory is affected according to the value of `order`.
-*Returns:* Atomically returns the value pointed to by `object` or by
-`this`.
 ``` cpp
-A::operator C() const volatile noexcept;
-A::operator C() const noexcept;
 ```
-*Effects:* `load()`
-*Returns:* The result of `load()`.
 ``` cpp
-C atomic_exchange(volatile A* object, C desired) noexcept;
-C atomic_exchange(A* object, C desired) noexcept;
-C atomic_exchange_explicit(volatile A* object, C desired, memory_order) noexcept;
-C atomic_exchange_explicit(A* object, C desired, memory_order) noexcept;
-C A::exchange(C desired, memory_order order = memory_order_seq_cst) volatile noexcept;
-C A::exchange(C desired, memory_order order = memory_order_seq_cst) noexcept;
 ```
-*Effects:* Atomically replaces the value pointed to by `object` or by
-`this` with `desired`. Memory is affected according to the value of
-`order`. These operations are atomic read-modify-write
 operations ([[intro.multithread]]).
-*Returns:* Atomically returns the value pointed to by `object` or by
-`this` immediately before the effects.
 ``` cpp
-bool atomic_compare_exchange_weak(volatile A* object, C* expected, C desired) noexcept;
-bool atomic_compare_exchange_weak(A* object, C* expected, C desired) noexcept;
-bool atomic_compare_exchange_strong(volatile A* object, C* expected, C desired) noexcept;
-bool atomic_compare_exchange_strong(A* object, C* expected, C desired) noexcept;
-bool atomic_compare_exchange_weak_explicit(volatile A* object, C* expected, C desired,
-    memory_order success, memory_order failure) noexcept;
-bool atomic_compare_exchange_weak_explicit(A* object, C* expected, C desired,
-    memory_order success, memory_order failure) noexcept;
-bool atomic_compare_exchange_strong_explicit(volatile A* object, C* expected, C desired,
-    memory_order success, memory_order failure) noexcept;
-bool atomic_compare_exchange_strong_explicit(A* object, C* expected, C desired,
-    memory_order success, memory_order failure) noexcept;
-bool A::compare_exchange_weak(C& expected, C desired,
                            memory_order success, memory_order failure) volatile noexcept;
-bool A::compare_exchange_weak(C& expected, C desired,
                            memory_order success, memory_order failure) noexcept;
-bool A::compare_exchange_strong(C& expected, C desired,
                              memory_order success, memory_order failure) volatile noexcept;
-bool A::compare_exchange_strong(C& expected, C desired,
                              memory_order success, memory_order failure) noexcept;
-bool A::compare_exchange_weak(C& expected, C desired,
                            memory_order order = memory_order_seq_cst) volatile noexcept;
-bool A::compare_exchange_weak(C& expected, C desired,
                            memory_order order = memory_order_seq_cst) noexcept;
-bool A::compare_exchange_strong(C& expected, C desired,
                              memory_order order = memory_order_seq_cst) volatile noexcept;
-bool A::compare_exchange_strong(C& expected, C desired,
                              memory_order order = memory_order_seq_cst) noexcept;
 ```
 *Requires:* The `failure` argument shall not be `memory_order_release`
-nor `memory_order_acq_rel`. The `failure` argument shall be no stronger
-than the `success` argument.
-*Effects:* Atomically, compares the contents of the memory pointed to by
-`object` or by `this` for equality with that in `expected`, and if true,
-replaces the contents of the memory pointed to by `object` or by `this`
-with that in `desired`, and if false, updates the contents of the memory
-in `expected` with the contents of the memory pointed to by `object` or
-by `this`. Further, if the comparison is true, memory is affected
-according to the value of `success`, and if the comparison is false,
-memory is affected according to the value of `failure`. When only one
 `memory_order` argument is supplied, the value of `success` is `order`,
 and the value of `failure` is `order` except that a value of
 `memory_order_acq_rel` shall be replaced by the value
 `memory_order_acquire` and a value of `memory_order_release` shall be
-replaced by the value `memory_order_relaxed`. If the operation returns
-`true`, these operations are atomic read-modify-write
-operations ([[intro.multithread]]). Otherwise, these operations are
-atomic load operations.
 *Returns:* The result of the comparison.
-For example, the effect of `atomic_compare_exchange_strong` is
 ``` cpp
-if (memcmp(object, expected, sizeof(*object)) == 0)
-  memcpy(object, &desired, sizeof(*object));
 else
-  memcpy(expected, object, sizeof(*object));
 ```
-the expected use of the compare-and-exchange operations is as follows.
 The compare-and-exchange operations will update `expected` when another
 iteration of the loop is needed.
 ``` cpp
 expected = current.load();
 do {
   desired = function(expected);
 } while (!current.compare_exchange_weak(expected, desired));
 ```
 Implementations should ensure that weak compare-and-exchange operations
 do not consistently return `false` unless either the atomic object has
 value different from `expected` or there are concurrent modifications to
 the atomic object.
-A weak compare-and-exchange operation may fail spuriously. That is, even
-when the contents of memory referred to by `expected` and `object` are
-equal, it may return false and store back to `expected` the same memory
-contents that were originally there. This spurious failure enables
-implementation of compare-and-exchange on a broader class of machines,
-e.g., load-locked store-conditional machines. A consequence of spurious
-failure is that nearly all uses of weak compare-and-exchange will be in
-a loop.
-When a compare-and-exchange is in a loop, the weak version will yield
-better performance on some platforms. When a weak compare-and-exchange
-would require a loop and a strong one would not, the strong one is
-preferable.
-The `memcpy` and `memcmp` semantics of the compare-and-exchange
-operations may result in failed comparisons for values that compare
-equal with `operator==` if the underlying type has padding bits, trap
-bits, or alternate representations of the same value. Thus,
-`compare_exchange_strong` should be used with extreme care. On the other
-hand, `compare_exchange_weak` should converge rapidly.
-The following operations perform arithmetic computations. The key,
-operator, and computation correspondence is:
-**Table: Atomic arithmetic computations** <a id="tab:atomic.arithmetic.computations">[tab:atomic.arithmetic.computations]</a>
-|       |     |                      |       |     |                      |
-| ----- | --- | -------------------- | ----- | --- | -------------------- |
-| `add` | `+` | addition             | `sub` | `-` | subtraction          |
-| `or`  | `|` | bitwise inclusive or | `xor` | `^` | bitwise exclusive or |
-| `and` | `&` | bitwise and          |       |     |                      |
-``` cpp
-C atomic_fetch_key(volatile A* object, M operand) noexcept;
-C atomic_fetch_key(A* object, M operand) noexcept;
-C atomic_fetch_key_explicit(volatile A* object, M operand, memory_order order) noexcept;
-C atomic_fetch_key_explicit(A* object, M operand, memory_order order) noexcept;
-C A::fetch_key(M operand, memory_order order = memory_order_seq_cst) volatile noexcept;
-C A::fetch_key(M operand, memory_order order = memory_order_seq_cst) noexcept;
-```
-*Effects:* Atomically replaces the value pointed to by `object` or by
-`this` with the result of the *computation* applied to the value pointed
-to by `object` or by `this` and the given `operand`. Memory is affected
-according to the value of `order`. These operations are atomic
-read-modify-write operations ([[intro.multithread]]).
-*Returns:* Atomically, the value pointed to by `object` or by `this`
-immediately before the effects.
-For signed integer types, arithmetic is defined to use two’s complement
-representation. There are no undefined results. For address types, the
-result may be an undefined address, but the operations otherwise have no
-undefined behavior.
-``` cpp
-C A::operator op=(M operand) volatile noexcept;
-C A::operator op=(M operand) noexcept;
-```
-*Effects:* `fetch_`*`key`*`(operand)`
-*Returns:* `fetch_`*`key`*`(operand) op operand`
-``` cpp
-C A::operator++(int) volatile noexcept;
-C A::operator++(int) noexcept;
-```
-*Returns:* `fetch_add(1)`
-``` cpp
-C A::operator--(int) volatile noexcept;
-C A::operator--(int) noexcept;
-```
-*Returns:* `fetch_sub(1)`
-``` cpp
-C A::operator++() volatile noexcept;
-C A::operator++() noexcept;
-```
-*Effects:* `fetch_add(1)`
-*Returns:* `fetch_add(1) + 1`
-``` cpp
-C A::operator--() volatile noexcept;
-C A::operator--() noexcept;
-```
-*Effects:* `fetch_sub(1)`
-*Returns:* `fetch_sub(1) - 1`

+### Operations on atomic types <a id="atomics.types.operations">[[atomics.types.operations]]</a>
+[*Note 1*: Many operations are volatile-qualified. The “volatile as
+device register” semantics have not changed in the standard. This
+qualification means that volatility is preserved when applying these
+operations to volatile objects. It does not mean that operations on
+non-volatile objects become volatile. — *end note*]
 ``` cpp
+atomic() noexcept = default;
 ```
+*Effects:* Leaves the atomic object in an uninitialized state.
+[*Note 1*: These semantics ensure compatibility with C. — *end note*]
 ``` cpp
+constexpr atomic(T desired) noexcept;
 ```
 *Effects:* Initializes the object with the value `desired`.
+Initialization is not an atomic operation ([[intro.multithread]]).
+[*Note 2*: It is possible to have an access to an atomic object `A`
+race with its construction, for example by communicating the address of
+the just-constructed object `A` to another thread via
+`memory_order_relaxed` operations on a suitable atomic pointer variable,
+and then immediately accessing `A` in the receiving thread. This results
+in undefined behavior. — *end note*]
 ``` cpp
 #define ATOMIC_VAR_INIT(value) see below
 ```
 The macro expands to a token sequence suitable for constant
 initialization of an atomic variable of static storage duration of a
+type that is initialization-compatible with `value`.
+[*Note 3*: This operation may need to initialize locks. — *end note*]
+Concurrent access to the variable being initialized, even via an atomic
+operation, constitutes a data race.
+[*Example 1*:
 ``` cpp
 atomic<int> v = ATOMIC_VAR_INIT(5);
 ```
+— *end example*]
+``` cpp
+static constexpr bool is_always_lock_free = implementation-defined  // whether a given atomic type's operations are always lock free;
+```
+The `static` data member `is_always_lock_free` is `true` if the atomic
+type’s operations are always lock-free, and `false` otherwise.
+[*Note 4*: The value of `is_always_lock_free` is consistent with the
+value of the corresponding `ATOMIC_..._LOCK_FREE` macro, if
+defined. — *end note*]
 ``` cpp
+bool is_lock_free() const volatile noexcept;
+bool is_lock_free() const noexcept;
 ```
+*Returns:* `true` if the object’s operations are lock-free, `false`
 otherwise.
+[*Note 5*: The return value of the `is_lock_free` member function is
+consistent with the value of `is_always_lock_free` for the same
+type. — *end note*]
 ``` cpp
+void store(T desired, memory_order order = memory_order_seq_cst) volatile noexcept;
+void store(T desired, memory_order order = memory_order_seq_cst) noexcept;
 ```
 *Requires:* The `order` argument shall not be `memory_order_consume`,
 `memory_order_acquire`, nor `memory_order_acq_rel`.
+*Effects:* Atomically replaces the value pointed to by `this` with the
+value of `desired`. Memory is affected according to the value of
+`order`.
 ``` cpp
+T operator=(T desired) volatile noexcept;
+T operator=(T desired) noexcept;
 ```
+*Effects:* Equivalent to: `store(desired)`.
+*Returns:* `desired`.
 ``` cpp
+T load(memory_order order = memory_order_seq_cst) const volatile noexcept;
+T load(memory_order order = memory_order_seq_cst) const noexcept;
 ```
 *Requires:* The `order` argument shall not be `memory_order_release` nor
 `memory_order_acq_rel`.
 *Effects:* Memory is affected according to the value of `order`.
+*Returns:* Atomically returns the value pointed to by `this`.
 ``` cpp
+operator T() const volatile noexcept;
+operator T() const noexcept;
 ```
+*Effects:* Equivalent to: `return load();`
 ``` cpp
+T exchange(T desired, memory_order order = memory_order_seq_cst) volatile noexcept;
+T exchange(T desired, memory_order order = memory_order_seq_cst) noexcept;
 ```
+*Effects:* Atomically replaces the value pointed to by `this` with
+`desired`. Memory is affected according to the value of `order`. These
+operations are atomic read-modify-write
 operations ([[intro.multithread]]).
+*Returns:* Atomically returns the value pointed to by `this` immediately
+before the effects.
 ``` cpp
+bool compare_exchange_weak(T& expected, T desired,
                            memory_order success, memory_order failure) volatile noexcept;
+bool compare_exchange_weak(T& expected, T desired,
                            memory_order success, memory_order failure) noexcept;
+bool compare_exchange_strong(T& expected, T desired,
                              memory_order success, memory_order failure) volatile noexcept;
+bool compare_exchange_strong(T& expected, T desired,
                              memory_order success, memory_order failure) noexcept;
+bool compare_exchange_weak(T& expected, T desired,
                            memory_order order = memory_order_seq_cst) volatile noexcept;
+bool compare_exchange_weak(T& expected, T desired,
                            memory_order order = memory_order_seq_cst) noexcept;
+bool compare_exchange_strong(T& expected, T desired,
                              memory_order order = memory_order_seq_cst) volatile noexcept;
+bool compare_exchange_strong(T& expected, T desired,
                              memory_order order = memory_order_seq_cst) noexcept;
 ```
 *Requires:* The `failure` argument shall not be `memory_order_release`
+nor `memory_order_acq_rel`.
+*Effects:* Retrieves the value in `expected`. It then atomically
+compares the contents of the memory pointed to by `this` for equality
+with that previously retrieved from `expected`, and if true, replaces
+the contents of the memory pointed to by `this` with that in `desired`.
+If and only if the comparison is true, memory is affected according to
+the value of `success`, and if the comparison is false, memory is
+affected according to the value of `failure`. When only one
 `memory_order` argument is supplied, the value of `success` is `order`,
 and the value of `failure` is `order` except that a value of
 `memory_order_acq_rel` shall be replaced by the value
 `memory_order_acquire` and a value of `memory_order_release` shall be
+replaced by the value `memory_order_relaxed`. If and only if the
+comparison is false then, after the atomic operation, the contents of
+the memory in `expected` are replaced by the value read from the memory
+pointed to by `this` during the atomic comparison. If the operation
+returns `true`, these operations are atomic read-modify-write
+operations ([[intro.multithread]]) on the memory pointed to by `this`.
+Otherwise, these operations are atomic load operations on that memory.
 *Returns:* The result of the comparison.
+[*Note 6*:
+For example, the effect of `compare_exchange_strong` is
 ``` cpp
+if (memcmp(this, &expected, sizeof(*this)) == 0)
+  memcpy(this, &desired, sizeof(*this));
 else
+  memcpy(expected, this, sizeof(*this));
 ```
+— *end note*]
+[*Example 2*:
+The expected use of the compare-and-exchange operations is as follows.
 The compare-and-exchange operations will update `expected` when another
 iteration of the loop is needed.
 ``` cpp
 expected = current.load();
 do {
   desired = function(expected);
 } while (!current.compare_exchange_weak(expected, desired));
 ```
+— *end example*]
+[*Example 3*:
+Because the expected value is updated only on failure, code releasing
+the memory containing the `expected` value on success will work. E.g.
+list head insertion will act atomically and would not introduce a data
+race in the following code:
+``` cpp
+do {
+  p->next = head; // make new list node point to the current head
+} while (!head.compare_exchange_weak(p->next, p)); // try to insert
+```
+— *end example*]
 Implementations should ensure that weak compare-and-exchange operations
 do not consistently return `false` unless either the atomic object has
 value different from `expected` or there are concurrent modifications to
 the atomic object.
+*Remarks:* A weak compare-and-exchange operation may fail spuriously.
+That is, even when the contents of memory referred to by `expected` and
+`this` are equal, it may return `false` and store back to `expected` the
+same memory contents that were originally there.
+[*Note 7*: This spurious failure enables implementation of
+compare-and-exchange on a broader class of machines, e.g., load-locked
+store-conditional machines. A consequence of spurious failure is that
+nearly all uses of weak compare-and-exchange will be in a loop. When a
+compare-and-exchange is in a loop, the weak version will yield better
+performance on some platforms. When a weak compare-and-exchange would
+require a loop and a strong one would not, the strong one is
+preferable. — *end note*]
+[*Note 8*: The `memcpy` and `memcmp` semantics of the
+compare-and-exchange operations may result in failed comparisons for
+values that compare equal with `operator==` if the underlying type has
+padding bits, trap bits, or alternate representations of the same value.
+Thus, `compare_exchange_strong` should be used with extreme care. On the
+other hand, `compare_exchange_weak` should converge
+rapidly. — *end note*]

Diff to HTML by rtfpessoa