[util.smartptr.atomic] - C++17 → C++20

Files changed (1) hide show

tmp/tmpfgf7ckqd/{from.md → to.md} +468 -0

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

	@@ -0,0 +1,468 @@

+### Partial specializations for smart pointers <a id="util.smartptr.atomic">[[util.smartptr.atomic]]</a>
+The library provides partial specializations of the `atomic` template
+for shared-ownership smart pointers [[smartptr]]. The behavior of all
+operations is as specified in [[atomics.types.generic]], unless
+specified otherwise. The template parameter `T` of these partial
+specializations may be an incomplete type.
+All changes to an atomic smart pointer in this subclause, and all
+associated `use_count` increments, are guaranteed to be performed
+atomically. Associated `use_count` decrements are sequenced after the
+atomic operation, but are not required to be part of it. Any associated
+deletion and deallocation are sequenced after the atomic update step and
+are not part of the atomic operation.
+[*Note 1*: If the atomic operation uses locks, locks acquired by the
+implementation will be held when any `use_count` adjustments are
+performed, and will not be held when any destruction or deallocation
+resulting from this is performed. — *end note*]
+[*Example 1*:
+``` cpp
+template<typename T> class atomic_list {
+  struct node {
+    T t;
+    shared_ptr<node> next;
+  };
+  atomic<shared_ptr<node>> head;
+public:
+  auto find(T t) const {
+    auto p = head.load();
+    while (p && p->t != t)
+      p = p->next;
+    return shared_ptr<node>(move(p));
+  }
+  void push_front(T t) {
+    auto p = make_shared<node>();
+    p->t = t;
+    p->next = head;
+    while (!head.compare_exchange_weak(p->next, p)) {}
+  }
+};
+```
+— *end example*]
+#### Partial specialization for `shared_ptr` <a id="util.smartptr.atomic.shared">[[util.smartptr.atomic.shared]]</a>
+``` cpp
+namespace std {
+  template<class T> struct atomic<shared_ptr<T>> {
+    using value_type = shared_ptr<T>;
+    static constexpr bool is_always_lock_free = implementation-defined  // whether a given atomic type's operations are always lock free;
+    bool is_lock_free() const noexcept;
+    constexpr atomic() noexcept;
+    atomic(shared_ptr<T> desired) noexcept;
+    atomic(const atomic&) = delete;
+    void operator=(const atomic&) = delete;
+    shared_ptr<T> load(memory_order order = memory_order::seq_cst) const noexcept;
+    operator shared_ptr<T>() const noexcept;
+    void store(shared_ptr<T> desired, memory_order order = memory_order::seq_cst) noexcept;
+    void operator=(shared_ptr<T> desired) noexcept;
+    shared_ptr<T> exchange(shared_ptr<T> desired,
+                           memory_order order = memory_order::seq_cst) noexcept;
+    bool compare_exchange_weak(shared_ptr<T>& expected, shared_ptr<T> desired,
+                               memory_order success, memory_order failure) noexcept;
+    bool compare_exchange_strong(shared_ptr<T>& expected, shared_ptr<T> desired,
+                                 memory_order success, memory_order failure) noexcept;
+    bool compare_exchange_weak(shared_ptr<T>& expected, shared_ptr<T> desired,
+                               memory_order order = memory_order::seq_cst) noexcept;
+    bool compare_exchange_strong(shared_ptr<T>& expected, shared_ptr<T> desired,
+                                 memory_order order = memory_order::seq_cst) noexcept;
+    void wait(shared_ptr<T> old, memory_order order = memory_order::seq_cst) const noexcept;
+    void notify_one() noexcept;
+    void notify_all() noexcept;
+  private:
+    shared_ptr<T> p;            // exposition only
+  };
+}
+```
+``` cpp
+constexpr atomic() noexcept;
+```
+*Effects:* Initializes `p{}`.
+``` cpp
+atomic(shared_ptr<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
+void store(shared_ptr<T> desired, memory_order order = memory_order::seq_cst) noexcept;
+```
+*Preconditions:* `order` is neither `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` as if by `p.swap(desired)`. Memory is affected
+according to the value of `order`.
+``` cpp
+void operator=(shared_ptr<T> desired) noexcept;
+```
+*Effects:* Equivalent to `store(desired)`.
+``` cpp
+shared_ptr<T> load(memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Preconditions:* `order` is neither `memory_order::release` nor
+`memory_order::acq_rel`.
+*Effects:* Memory is affected according to the value of `order`.
+*Returns:* Atomically returns `p`.
+``` cpp
+operator shared_ptr<T>() const noexcept;
+```
+*Effects:* Equivalent to: `return load();`
+``` cpp
+shared_ptr<T> exchange(shared_ptr<T> desired, memory_order order = memory_order::seq_cst) noexcept;
+```
+*Effects:* Atomically replaces `p` with `desired` as if by
+`p.swap(desired)`. Memory is affected according to the value of `order`.
+This is an atomic read-modify-write operation [[intro.races]].
+*Returns:* Atomically returns the value of `p` immediately before the
+effects.
+``` cpp
+bool compare_exchange_weak(shared_ptr<T>& expected, shared_ptr<T> desired,
+                           memory_order success, memory_order failure) noexcept;
+bool compare_exchange_strong(shared_ptr<T>& expected, shared_ptr<T> desired,
+                             memory_order success, memory_order failure) noexcept;
+```
+*Preconditions:* `failure` is neither `memory_order::release` nor
+`memory_order::acq_rel`.
+*Effects:* If `p` is equivalent to `expected`, assigns `desired` to `p`
+and has synchronization semantics corresponding to the value of
+`success`, otherwise assigns `p` to `expected` and has synchronization
+semantics corresponding to the value of `failure`.
+*Returns:* `true` if `p` was equivalent to `expected`, `false`
+otherwise.
+*Remarks:* Two `shared_ptr` objects are equivalent if they store the
+same pointer value and either share ownership or are both empty. The
+weak form may fail spuriously. See [[atomics.types.operations]].
+If the operation returns `true`, `expected` is not accessed after the
+atomic update and the operation is an atomic read-modify-write
+operation [[intro.multithread]] on the memory pointed to by `this`.
+Otherwise, the operation is an atomic load operation on that memory, and
+`expected` is updated with the existing value read from the atomic
+object in the attempted atomic update. The `use_count` update
+corresponding to the write to `expected` is part of the atomic
+operation. The write to `expected` itself is not required to be part of
+the atomic operation.
+``` cpp
+bool compare_exchange_weak(shared_ptr<T>& expected, shared_ptr<T> desired,
+                           memory_order order = memory_order::seq_cst) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+return compare_exchange_weak(expected, desired, order, fail_order);
+```
+where `fail_order` is the same as `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`.
+``` cpp
+bool compare_exchange_strong(shared_ptr<T>& expected, shared_ptr<T> desired,
+                             memory_order order = memory_order::seq_cst) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+return compare_exchange_strong(expected, desired, order, fail_order);
+```
+where `fail_order` is the same as `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`.
+``` cpp
+void wait(shared_ptr<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 it to `old`.
+- If the two are not equivalent, returns.
+- Blocks until it is unblocked by an atomic notifying operation or is
+  unblocked spuriously.
+*Remarks:* Two `shared_ptr` objects are equivalent if they store the
+same pointer and either share ownership or are both empty. This function
+is an atomic waiting operation [[atomics.wait]].
+``` cpp
+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() 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]].
+#### Partial specialization for `weak_ptr` <a id="util.smartptr.atomic.weak">[[util.smartptr.atomic.weak]]</a>
+``` cpp
+namespace std {
+  template<class T> struct atomic<weak_ptr<T>> {
+    using value_type = weak_ptr<T>;
+    static constexpr bool is_always_lock_free = implementation-defined  // whether a given atomic type's operations are always lock free;
+    bool is_lock_free() const noexcept;
+    constexpr atomic() noexcept;
+    atomic(weak_ptr<T> desired) noexcept;
+    atomic(const atomic&) = delete;
+    void operator=(const atomic&) = delete;
+    weak_ptr<T> load(memory_order order = memory_order::seq_cst) const noexcept;
+    operator weak_ptr<T>() const noexcept;
+    void store(weak_ptr<T> desired, memory_order order = memory_order::seq_cst) noexcept;
+    void operator=(weak_ptr<T> desired) noexcept;
+    weak_ptr<T> exchange(weak_ptr<T> desired,
+                         memory_order order = memory_order::seq_cst) noexcept;
+    bool compare_exchange_weak(weak_ptr<T>& expected, weak_ptr<T> desired,
+                               memory_order success, memory_order failure) noexcept;
+    bool compare_exchange_strong(weak_ptr<T>& expected, weak_ptr<T> desired,
+                                 memory_order success, memory_order failure) noexcept;
+    bool compare_exchange_weak(weak_ptr<T>& expected, weak_ptr<T> desired,
+                               memory_order order = memory_order::seq_cst) noexcept;
+    bool compare_exchange_strong(weak_ptr<T>& expected, weak_ptr<T> desired,
+                                 memory_order order = memory_order::seq_cst) noexcept;
+    void wait(weak_ptr<T> old, memory_order order = memory_order::seq_cst) const noexcept;
+    void notify_one() noexcept;
+    void notify_all() noexcept;
+  private:
+    weak_ptr<T> p;              // exposition only
+  };
+}
+```
+``` cpp
+constexpr atomic() noexcept;
+```
+*Effects:* Initializes `p{}`.
+``` cpp
+atomic(weak_ptr<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
+void store(weak_ptr<T> desired, memory_order order = memory_order::seq_cst) noexcept;
+```
+*Preconditions:* `order` is neither `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` as if by `p.swap(desired)`. Memory is affected
+according to the value of `order`.
+``` cpp
+void operator=(weak_ptr<T> desired) noexcept;
+```
+*Effects:* Equivalent to `store(desired)`.
+``` cpp
+weak_ptr<T> load(memory_order order = memory_order::seq_cst) const noexcept;
+```
+*Preconditions:* `order` is neither `memory_order::release` nor
+`memory_order::acq_rel`.
+*Effects:* Memory is affected according to the value of `order`.
+*Returns:* Atomically returns `p`.
+``` cpp
+operator weak_ptr<T>() const noexcept;
+```
+*Effects:* Equivalent to: `return load();`
+``` cpp
+weak_ptr<T> exchange(weak_ptr<T> desired, memory_order order = memory_order::seq_cst) noexcept;
+```
+*Effects:* Atomically replaces `p` with `desired` as if by
+`p.swap(desired)`. Memory is affected according to the value of `order`.
+This is an atomic read-modify-write operation [[intro.races]].
+*Returns:* Atomically returns the value of `p` immediately before the
+effects.
+``` cpp
+bool compare_exchange_weak(weak_ptr<T>& expected, weak_ptr<T> desired,
+                           memory_order success, memory_order failure) noexcept;
+bool compare_exchange_strong(weak_ptr<T>& expected, weak_ptr<T> desired,
+                             memory_order success, memory_order failure) noexcept;
+```
+*Preconditions:* `failure` is neither `memory_order::release` nor
+`memory_order::acq_rel`.
+*Effects:* If `p` is equivalent to `expected`, assigns `desired` to `p`
+and has synchronization semantics corresponding to the value of
+`success`, otherwise assigns `p` to `expected` and has synchronization
+semantics corresponding to the value of `failure`.
+*Returns:* `true` if `p` was equivalent to `expected`, `false`
+otherwise.
+*Remarks:* Two `weak_ptr` objects are equivalent if they store the same
+pointer value and either share ownership or are both empty. The weak
+form may fail spuriously. See [[atomics.types.operations]].
+If the operation returns `true`, `expected` is not accessed after the
+atomic update and the operation is an atomic read-modify-write
+operation [[intro.multithread]] on the memory pointed to by `this`.
+Otherwise, the operation is an atomic load operation on that memory, and
+`expected` is updated with the existing value read from the atomic
+object in the attempted atomic update. The `use_count` update
+corresponding to the write to `expected` is part of the atomic
+operation. The write to `expected` itself is not required to be part of
+the atomic operation.
+``` cpp
+bool compare_exchange_weak(weak_ptr<T>& expected, weak_ptr<T> desired,
+                           memory_order order = memory_order::seq_cst) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+return compare_exchange_weak(expected, desired, order, fail_order);
+```
+where `fail_order` is the same as `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`.
+``` cpp
+bool compare_exchange_strong(weak_ptr<T>& expected, weak_ptr<T> desired,
+                             memory_order order = memory_order::seq_cst) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+return compare_exchange_strong(expected, desired, order, fail_order);
+```
+where `fail_order` is the same as `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`.
+``` cpp
+void wait(weak_ptr<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 it to `old`.
+- If the two are not equivalent, returns.
+- Blocks until it is unblocked by an atomic notifying operation or is
+  unblocked spuriously.
+*Remarks:* Two `weak_ptr` objects are equivalent if they store the same
+pointer and either share ownership or are both empty. This function is
+an atomic waiting operation [[atomics.wait]].
+``` cpp
+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() 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