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

Files changed (1) hide show

tmp/tmpxu4rcz14/{from.md → to.md} +169 -86

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

@@ -1,64 +1,38 @@
 ### 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;
@@ -66,63 +40,79 @@ 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
@@ -133,57 +123,60 @@ bool compare_exchange_weak(T& expected, T desired,
 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.
@@ -194,16 +187,16 @@ do {
 } 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
@@ -219,22 +212,112 @@ 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*]

 ### Operations on atomic types <a id="atomics.types.operations">[[atomics.types.operations]]</a>
 ``` cpp
+constexpr atomic() noexcept(is_nothrow_default_constructible_v<T>);
 ```
+*Mandates:* `is_default_constructible_v<T>` is `true`.
+*Effects:* Initializes the atomic object with the value of `T()`.
+Initialization is not an atomic operation [[intro.multithread]].
 ``` cpp
 constexpr atomic(T desired) noexcept;
 ```
 *Effects:* Initializes the object with the value `desired`.
+Initialization is not an atomic operation [[intro.multithread]].
+[*Note 1*: 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
 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 2*: 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;
 ```
 *Returns:* `true` if the object’s operations are lock-free, `false`
 otherwise.
+[*Note 3*: 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;
 ```
+*Preconditions:* The `order` argument is neither
+`memory_order::consume`, `memory_order::acquire`, nor
+`memory_order::acq_rel`.
+*Constraints:* For the `volatile` overload of this function,
+`is_always_lock_free` is `true`.
 *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;
 ```
+*Constraints:* For the `volatile` overload of this function,
+`is_always_lock_free` is `true`.
+*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;
 ```
+*Preconditions:* The `order` argument is neither `memory_order::release`
+nor `memory_order::acq_rel`.
+*Constraints:* For the `volatile` overload of this function,
+`is_always_lock_free` is `true`.
 *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;
 ```
+*Constraints:* For the `volatile` overload of this function,
+`is_always_lock_free` is `true`.
 *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;
 ```
+*Constraints:* For the `volatile` overload of this function,
+`is_always_lock_free` is `true`.
 *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_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;
 ```
+*Preconditions:* The `failure` argument is neither
+`memory_order::release` nor `memory_order::acq_rel`.
+*Constraints:* For the `volatile` overload of this function,
+`is_always_lock_free` is `true`.
 *Effects:* Retrieves the value in `expected`. It then atomically
+compares the value representation of the value pointed to by `this` for
+equality with that previously retrieved from `expected`, and if true,
+replaces the value 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 value in `expected` is replaced by the
+value 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 4*:
+For example, the effect of `compare_exchange_strong` on objects without
+padding bits [[basic.types]] is
 ``` cpp
 if (memcmp(this, &expected, sizeof(*this)) == 0)
   memcpy(this, &desired, sizeof(*this));
 else
   memcpy(expected, this, sizeof(*this));
 ```
 — *end note*]
+[*Example 1*:
 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.
 } while (!current.compare_exchange_weak(expected, desired));
 ```
 — *end example*]
+[*Example 2*:
 Because the expected value is updated only on failure, code releasing
+the memory containing the `expected` value on success will work. For
+example, 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
 *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 5*: 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 6*: Under cases where the `memcpy` and `memcmp` semantics of the
+compare-and-exchange operations apply, the outcome might be failed
+comparisons for values that compare equal with `operator==` if the value
+representation has trap bits or alternate representations of the same
+value. Notably, on implementations conforming to ISO/IEC/IEEE 60559,
+floating-point `-0.0` and `+0.0` will not compare equal with `memcmp`
+but will compare equal with `operator==`, and NaNs with the same payload
+will compare equal with `memcmp` but will not compare equal with
+`operator==`. — *end note*]
+[*Note 7*:
+Because compare-and-exchange acts on an object’s value representation,
+padding bits that never participate in the object’s value representation
+are ignored. As a consequence, the following code is guaranteed to avoid
+spurious failure:
+``` cpp
+struct padded {
+  char clank = 0x42;
+  // Padding here.
+  unsigned biff = 0xC0DEFEFE;
+};
+atomic<padded> pad = {};
+bool zap() {
+  padded expected, desired{0, 0};
+  return pad.compare_exchange_strong(expected, desired);
+}
+```
+— *end note*]
+[*Note 8*:
+For a union with bits that participate in the value representation of
+some members but not others, compare-and-exchange might always fail.
+This is because such padding bits have an indeterminate value when they
+do not participate in the value representation of the active member. As
+a consequence, the following code is not guaranteed to ever succeed:
+``` cpp
+union pony {
+  double celestia = 0.;
+  short luna;       // padded
+};
+atomic<pony> princesses = {};
+bool party(pony desired) {
+  pony expected;
+  return princesses.compare_exchange_strong(expected, desired);
+}
+```
+— *end note*]
+``` cpp
+void wait(T old, memory_order order = memory_order::seq_cst) const volatile noexcept;
+void wait(T old, memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Preconditions:* `order` is neither `memory_order::release` nor
+`memory_order::acq_rel`.
+*Effects:* Repeatedly performs the following steps, in order:
+- Evaluates `load(order)` and compares its value representation for
+  equality against that of `old`.
+- If they compare unequal, returns.
+- Blocks until it is unblocked by an atomic notifying operation or is
+  unblocked spuriously.
+*Remarks:* This function is an atomic waiting
+operation [[atomics.wait]].
+``` cpp
+void notify_one() volatile noexcept;
+void notify_one() noexcept;
+```
+*Effects:* Unblocks the execution of at least one atomic waiting
+operation that is eligible to be unblocked [[atomics.wait]] by this
+call, if any such atomic waiting operations exist.
+*Remarks:* This function is an atomic notifying
+operation [[atomics.wait]].
+``` cpp
+void notify_all() volatile noexcept;
+void notify_all() noexcept;
+```
+*Effects:* Unblocks the execution of all atomic waiting operations that
+are eligible to be unblocked [[atomics.wait]] by this call.
+*Remarks:* This function is an atomic notifying
+operation [[atomics.wait]].

Diff to HTML by rtfpessoa