[atomics.ref.generic] - C++17 → C++20

Files changed (1) hide show

tmp/tmpn6yd1nm5/{from.md → to.md} +568 -0

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

	@@ -0,0 +1,568 @@

+## Class template `atomic_ref` <a id="atomics.ref.generic">[[atomics.ref.generic]]</a>
+``` cpp
+namespace std {
+  template<class T> struct atomic_ref {
+  private:
+    T* ptr;             // exposition only
+  public:
+    using value_type = T;
+    static constexpr size_t required_alignment = implementation-defined  // required alignment for atomic_ref type's operations;
+    static constexpr bool is_always_lock_free = implementation-defined  // whether a given atomic_ref type's operations are always lock free;
+    bool is_lock_free() const noexcept;
+    explicit atomic_ref(T&);
+    atomic_ref(const atomic_ref&) noexcept;
+    atomic_ref& operator=(const atomic_ref&) = delete;
+    void store(T, memory_order = memory_order::seq_cst) const noexcept;
+    T operator=(T) const noexcept;
+    T load(memory_order = memory_order::seq_cst) const noexcept;
+    operator T() const noexcept;
+    T exchange(T, memory_order = memory_order::seq_cst) const noexcept;
+    bool compare_exchange_weak(T&, T,
+                               memory_order, memory_order) const noexcept;
+    bool compare_exchange_strong(T&, T,
+                                 memory_order, memory_order) const noexcept;
+    bool compare_exchange_weak(T&, T,
+                               memory_order = memory_order::seq_cst) const noexcept;
+    bool compare_exchange_strong(T&, T,
+                                 memory_order = memory_order::seq_cst) const noexcept;
+    void wait(T, memory_order = memory_order::seq_cst) const noexcept;
+    void notify_one() const noexcept;
+    void notify_all() const noexcept;
+  };
+}
+```
+An `atomic_ref` object applies atomic operations [[atomics.general]] to
+the object referenced by `*ptr` such that, for the lifetime
+[[basic.life]] of the `atomic_ref` object, the object referenced by
+`*ptr` is an atomic object [[intro.races]].
+The program is ill-formed if `is_trivially_copyable_v<T>` is `false`.
+The lifetime [[basic.life]] of an object referenced by `*ptr` shall
+exceed the lifetime of all `atomic_ref`s that reference the object.
+While any `atomic_ref` instances exist that reference the `*ptr` object,
+all accesses to that object shall exclusively occur through those
+`atomic_ref` instances. No subobject of the object referenced by
+`atomic_ref` shall be concurrently referenced by any other `atomic_ref`
+object.
+Atomic operations applied to an object through a referencing
+`atomic_ref` are atomic with respect to atomic operations applied
+through any other `atomic_ref` referencing the same object.
+[*Note 1*: Atomic operations or the `atomic_ref` constructor could
+acquire a shared resource, such as a lock associated with the referenced
+object, to enable atomic operations to be applied to the referenced
+object. — *end note*]
+### Operations <a id="atomics.ref.ops">[[atomics.ref.ops]]</a>
+``` cpp
+static constexpr size_t required_alignment;
+```
+The alignment required for an object to be referenced by an atomic
+reference, which is at least `alignof(T)`.
+[*Note 1*: Hardware could require an object referenced by an
+`atomic_ref` to have stricter alignment [[basic.align]] than other
+objects of type `T`. Further, whether operations on an `atomic_ref` are
+lock-free could depend on the alignment of the referenced object. For
+example, lock-free operations on `std::complex<double>` could be
+supported only if aligned to `2*alignof(double)`. — *end note*]
+``` cpp
+static constexpr bool is_always_lock_free;
+```
+The static data member `is_always_lock_free` is `true` if the
+`atomic_ref` type’s operations are always lock-free, and `false`
+otherwise.
+``` cpp
+bool is_lock_free() const noexcept;
+```
+*Returns:* `true` if operations on all objects of the type
+`atomic_ref<T>` are lock-free, `false` otherwise.
+``` cpp
+atomic_ref(T& obj);
+```
+*Preconditions:* The referenced object is aligned to
+`required_alignment`.
+*Ensures:* `*this` references `obj`.
+*Throws:* Nothing.
+``` cpp
+atomic_ref(const atomic_ref& ref) noexcept;
+```
+*Ensures:* `*this` references the object referenced by `ref`.
+``` cpp
+void store(T desired, memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Preconditions:* The `order` argument is neither
+`memory_order::consume`, `memory_order::acquire`, nor
+`memory_order::acq_rel`.
+*Effects:* Atomically replaces the value referenced by `*ptr` with the
+value of `desired`. Memory is affected according to the value of
+`order`.
+``` cpp
+T operator=(T desired) const noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+store(desired);
+return desired;
+```
+``` cpp
+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`.
+*Effects:* Memory is affected according to the value of `order`.
+*Returns:* Atomically returns the value referenced by `*ptr`.
+``` cpp
+operator T() const noexcept;
+```
+*Effects:* Equivalent to: `return load();`
+``` cpp
+T exchange(T desired, memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Effects:* Atomically replaces the value referenced by `*ptr` with
+`desired`. Memory is affected according to the value of `order`. This
+operation is an atomic read-modify-write
+operation [[intro.multithread]].
+*Returns:* Atomically returns the value referenced by `*ptr` immediately
+before the effects.
+``` cpp
+bool compare_exchange_weak(T& expected, T desired,
+                           memory_order success, memory_order failure) const noexcept;
+bool compare_exchange_strong(T& expected, T desired,
+                             memory_order success, memory_order failure) const noexcept;
+bool compare_exchange_weak(T& expected, T desired,
+                           memory_order order = memory_order::seq_cst) const noexcept;
+bool compare_exchange_strong(T& expected, T desired,
+                             memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Preconditions:* The `failure` argument is neither
+`memory_order::release` nor `memory_order::acq_rel`.
+*Effects:* Retrieves the value in `expected`. It then atomically
+compares the value representation of the value referenced by `*ptr` for
+equality with that previously retrieved from `expected`, and if `true`,
+replaces the value referenced by `*ptr` 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 read from the value referenced by `*ptr` during the atomic
+comparison. If the operation returns `true`, these operations are atomic
+read-modify-write operations [[intro.races]] on the value referenced by
+`*ptr`. Otherwise, these operations are atomic load operations on that
+memory.
+*Returns:* The result of the comparison.
+*Remarks:* A weak compare-and-exchange operation may fail spuriously.
+That is, even when the contents of memory referred to by `expected` and
+`ptr` are equal, it may return `false` and store back to `expected` the
+same memory contents that were originally there.
+[*Note 2*: 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*]
+``` cpp
+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]]
+on atomic object `*ptr`.
+``` cpp
+void notify_one() const noexcept;
+```
+*Effects:* Unblocks the execution of at least one atomic waiting
+operation on `*ptr` 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]] on atomic object `*ptr`.
+``` cpp
+void notify_all() const noexcept;
+```
+*Effects:* Unblocks the execution of all atomic waiting operations on
+`*ptr` that are eligible to be unblocked [[atomics.wait]] by this call.
+*Remarks:* This function is an atomic notifying
+operation [[atomics.wait]] on atomic object `*ptr`.
+### Specializations for integral types <a id="atomics.ref.int">[[atomics.ref.int]]</a>
+There are specializations of the `atomic_ref` class template for the
+integral types `char`, `signed char`, `unsigned char`, `short`,
+`unsigned short`, `int`, `unsigned int`, `long`, `unsigned long`,
+`long long`, `unsigned long long`, `char8_t`, `char16_t`, `char32_t`,
+`wchar_t`, and any other types needed by the typedefs in the header
+`<cstdint>`. For each such type `integral`, the specialization
+`atomic_ref<integral>` provides additional atomic operations appropriate
+to integral types.
+[*Note 1*: The specialization `atomic_ref<bool>` uses the primary
+template [[atomics.ref.generic]]. — *end note*]
+``` cpp
+namespace std {
+  template<> struct atomic_ref<integral> {
+  private:
+    integral* ptr;        // exposition only
+  public:
+    using value_type = integral;
+    using difference_type = value_type;
+    static constexpr size_t required_alignment = implementation-defined  // required alignment for atomic_ref type's operations;
+    static constexpr bool is_always_lock_free = implementation-defined  // whether a given atomic_ref type's operations are always lock free;
+    bool is_lock_free() const noexcept;
+    explicit atomic_ref(integral&);
+    atomic_ref(const atomic_ref&) noexcept;
+    atomic_ref& operator=(const atomic_ref&) = delete;
+    void store(integral, memory_order = memory_order::seq_cst) const noexcept;
+    integral operator=(integral) const noexcept;
+    integral load(memory_order = memory_order::seq_cst) const noexcept;
+    operator integral() const noexcept;
+    integral exchange(integral,
+                      memory_order = memory_order::seq_cst) const noexcept;
+    bool compare_exchange_weak(integral&, integral,
+                               memory_order, memory_order) const noexcept;
+    bool compare_exchange_strong(integral&, integral,
+                                 memory_order, memory_order) const noexcept;
+    bool compare_exchange_weak(integral&, integral,
+                               memory_order = memory_order::seq_cst) const noexcept;
+    bool compare_exchange_strong(integral&, integral,
+                                 memory_order = memory_order::seq_cst) const noexcept;
+    integral fetch_add(integral,
+                       memory_order = memory_order::seq_cst) const noexcept;
+    integral fetch_sub(integral,
+                       memory_order = memory_order::seq_cst) const noexcept;
+    integral fetch_and(integral,
+                       memory_order = memory_order::seq_cst) const noexcept;
+    integral fetch_or(integral,
+                      memory_order = memory_order::seq_cst) const noexcept;
+    integral fetch_xor(integral,
+                       memory_order = memory_order::seq_cst) const noexcept;
+    integral operator++(int) const noexcept;
+    integral operator--(int) const noexcept;
+    integral operator++() const noexcept;
+    integral operator--() const noexcept;
+    integral operator+=(integral) const noexcept;
+    integral operator-=(integral) const noexcept;
+    integral operator&=(integral) const noexcept;
+    integral operator|=(integral) const noexcept;
+    integral operator^=(integral) const noexcept;
+    void wait(integral, memory_order = memory_order::seq_cst) const noexcept;
+    void notify_one() const noexcept;
+    void notify_all() const noexcept;
+  };
+}
+```
+Descriptions are provided below only for members that differ from the
+primary template.
+The following operations perform arithmetic computations. The key,
+operator, and computation correspondence is identified in
+[[atomic.types.int.comp]].
+``` cpp
+integral fetch_key(integral operand, memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Effects:* Atomically replaces the value referenced by `*ptr` with the
+result of the computation applied to the value referenced by `*ptr` and
+the given operand. Memory is affected according to the value of `order`.
+These operations are atomic read-modify-write
+operations [[intro.races]].
+*Returns:* Atomically, the value referenced by `*ptr` immediately before
+the effects.
+*Remarks:* For signed integer types, the result is as if the object
+value and parameters were converted to their corresponding unsigned
+types, the computation performed on those types, and the result
+converted back to the signed type.
+[*Note 1*: There are no undefined results arising from the
+computation. — *end note*]
+``` cpp
+integral operator op=(integral operand) const noexcept;
+```
+*Effects:* Equivalent to:
+`return fetch_`*`key`*`(operand) `*`op`*` operand;`
+### Specializations for floating-point types <a id="atomics.ref.float">[[atomics.ref.float]]</a>
+There are specializations of the `atomic_ref` class template for the
+floating-point types `float`, `double`, and `long double`. For each such
+type `floating-point`, the specialization `atomic_ref<floating-point>`
+provides additional atomic operations appropriate to floating-point
+types.
+``` cpp
+namespace std {
+  template<> struct atomic_ref<floating-point> {
+  private:
+    floating-point* ptr;  // exposition only
+  public:
+    using value_type = floating-point;
+    using difference_type = value_type;
+    static constexpr size_t required_alignment = implementation-defined  // required alignment for atomic_ref type's operations;
+    static constexpr bool is_always_lock_free = implementation-defined  // whether a given atomic_ref type's operations are always lock free;
+    bool is_lock_free() const noexcept;
+    explicit atomic_ref(floating-point&);
+    atomic_ref(const atomic_ref&) noexcept;
+    atomic_ref& operator=(const atomic_ref&) = delete;
+    void store(floating-point, memory_order = memory_order::seq_cst) const noexcept;
+    floating-point operator=(floating-point) const noexcept;
+    floating-point load(memory_order = memory_order::seq_cst) const noexcept;
+    operator floating-point() const noexcept;
+    floating-point exchange(floating-point,
+                            memory_order = memory_order::seq_cst) const noexcept;
+    bool compare_exchange_weak(floating-point&, floating-point,
+                               memory_order, memory_order) const noexcept;
+    bool compare_exchange_strong(floating-point&, floating-point,
+                                 memory_order, memory_order) const noexcept;
+    bool compare_exchange_weak(floating-point&, floating-point,
+                               memory_order = memory_order::seq_cst) const noexcept;
+    bool compare_exchange_strong(floating-point&, floating-point,
+                                 memory_order = memory_order::seq_cst) const noexcept;
+    floating-point fetch_add(floating-point,
+                             memory_order = memory_order::seq_cst) const noexcept;
+    floating-point fetch_sub(floating-point,
+                             memory_order = memory_order::seq_cst) const noexcept;
+    floating-point operator+=(floating-point) const noexcept;
+    floating-point operator-=(floating-point) const noexcept;
+    void wait(floating-point, memory_order = memory_order::seq_cst) const noexcept;
+    void notify_one() const noexcept;
+    void notify_all() const noexcept;
+  };
+}
+```
+Descriptions are provided below only for members that differ from the
+primary template.
+The following operations perform arithmetic computations. The key,
+operator, and computation correspondence are identified in
+[[atomic.types.int.comp]].
+``` cpp
+floating-point fetch_key(floating-point operand,
+                          memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Effects:* Atomically replaces the value referenced by `*ptr` with the
+result of the computation applied to the value referenced by `*ptr` and
+the given operand. Memory is affected according to the value of `order`.
+These operations are atomic read-modify-write
+operations [[intro.races]].
+*Returns:* Atomically, the value referenced by `*ptr` immediately before
+the effects.
+*Remarks:* If the result is not a representable value for its
+type [[expr.pre]], the result is unspecified, but the operations
+otherwise have no undefined behavior. Atomic arithmetic operations on
+*`floating-point`* should conform to the
+`std::numeric_limits<`*`floating-point`*`>` traits associated with the
+floating-point type [[limits.syn]]. The floating-point
+environment [[cfenv]] for atomic arithmetic operations on
+*`floating-point`* may be different than the calling thread’s
+floating-point environment.
+``` cpp
+floating-point operator op=(floating-point operand) const noexcept;
+```
+*Effects:* Equivalent to:
+`return fetch_`*`key`*`(operand) `*`op`*` operand;`
+### Partial specialization for pointers <a id="atomics.ref.pointer">[[atomics.ref.pointer]]</a>
+``` cpp
+namespace std {
+  template<class T> struct atomic_ref<T*> {
+  private:
+    T** ptr;        // exposition only
+  public:
+    using value_type = T*;
+    using difference_type = ptrdiff_t;
+    static constexpr size_t required_alignment = implementation-defined  // required alignment for atomic_ref type's operations;
+    static constexpr bool is_always_lock_free = implementation-defined  // whether a given atomic_ref type's operations are always lock free;
+    bool is_lock_free() const noexcept;
+    explicit atomic_ref(T*&);
+    atomic_ref(const atomic_ref&) noexcept;
+    atomic_ref& operator=(const atomic_ref&) = delete;
+    void store(T*, memory_order = memory_order::seq_cst) const noexcept;
+    T* operator=(T*) const noexcept;
+    T* load(memory_order = memory_order::seq_cst) const noexcept;
+    operator T*() const noexcept;
+    T* exchange(T*, memory_order = memory_order::seq_cst) const noexcept;
+    bool compare_exchange_weak(T*&, T*,
+                               memory_order, memory_order) const noexcept;
+    bool compare_exchange_strong(T*&, T*,
+                                 memory_order, memory_order) const noexcept;
+    bool compare_exchange_weak(T*&, T*,
+                               memory_order = memory_order::seq_cst) const noexcept;
+    bool compare_exchange_strong(T*&, T*,
+                                 memory_order = memory_order::seq_cst) const noexcept;
+    T* fetch_add(difference_type, memory_order = memory_order::seq_cst) const noexcept;
+    T* fetch_sub(difference_type, memory_order = memory_order::seq_cst) const noexcept;
+    T* operator++(int) const noexcept;
+    T* operator--(int) const noexcept;
+    T* operator++() const noexcept;
+    T* operator--() const noexcept;
+    T* operator+=(difference_type) const noexcept;
+    T* operator-=(difference_type) const noexcept;
+    void wait(T*, memory_order = memory_order::seq_cst) const noexcept;
+    void notify_one() const noexcept;
+    void notify_all() const noexcept;
+  };
+}
+```
+Descriptions are provided below only for members that differ from the
+primary template.
+The following operations perform arithmetic computations. The key,
+operator, and computation correspondence is identified in
+[[atomic.types.pointer.comp]].
+``` cpp
+T* fetch_key(difference_type operand, memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Mandates:* `T` is a complete object type.
+*Effects:* Atomically replaces the value referenced by `*ptr` with the
+result of the computation applied to the value referenced by `*ptr` and
+the given operand. Memory is affected according to the value of `order`.
+These operations are atomic read-modify-write
+operations [[intro.races]].
+*Returns:* Atomically, the value referenced by `*ptr` immediately before
+the effects.
+*Remarks:* The result may be an undefined address, but the operations
+otherwise have no undefined behavior.
+``` cpp
+T* operator op=(difference_type operand) const noexcept;
+```
+*Effects:* Equivalent to:
+`return fetch_`*`key`*`(operand) `*`op`*` operand;`
+### Member operators common to integers and pointers to objects <a id="atomics.ref.memop">[[atomics.ref.memop]]</a>
+``` cpp
+value_type operator++(int) const noexcept;
+```
+*Effects:* Equivalent to: `return fetch_add(1);`
+``` cpp
+value_type operator--(int) const noexcept;
+```
+*Effects:* Equivalent to: `return fetch_sub(1);`
+``` cpp
+value_type operator++() const noexcept;
+```
+*Effects:* Equivalent to: `return fetch_add(1) + 1;`
+``` cpp
+value_type operator--() const noexcept;
+```
+*Effects:* Equivalent to: `return fetch_sub(1) - 1;`

Diff to HTML by rtfpessoa