Difference between revisions of "cpp/memory/shared ptr/atomic"

Latest revision as of 23:04, 20 October 2024

Defined in header `<memory>`
template< class T > bool atomic_is_lock_free( const std::shared_ptr<T>* p );	(1)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > std::shared_ptr<T> atomic_load( const std::shared_ptr<T>* p );	(2)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > std::shared_ptr<T> atomic_load_explicit ( const std::shared_ptr<T>* p, std::memory_order mo );	(3)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > void atomic_store( std::shared_ptr<T>* p, std::shared_ptr<T> r );	(4)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > void atomic_store_explicit ( std::shared_ptr<T>* p, std::shared_ptr<T> r, std::memory_order mo );	(5)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > std::shared_ptr<T> atomic_exchange ( std::shared_ptr<T>* p, std::shared_ptr<T> r );	(6)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > std::shared_ptr<T> atomic_exchange_explicit ( std::shared_ptr<T>* p, std::shared_ptr<T> r, std::memory_order mo );	(7)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > bool atomic_compare_exchange_weak ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected, std::shared_ptr<T> desired );	(8)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > bool atomic_compare_exchange_strong ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected, std::shared_ptr<T> desired );	(9)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > bool atomic_compare_exchange_strong_explicit ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected, std::shared_ptr<T> desired, std::memory_order success, std::memory_order failure );	(10)	(since C++11) (deprecated in C++20) (removed in C++26)
template< class T > bool atomic_compare_exchange_weak_explicit ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected, std::shared_ptr<T> desired, std::memory_order success, std::memory_order failure );	(11)	(since C++11) (deprecated in C++20) (removed in C++26)

If multiple threads of execution access the same std::shared_ptr object without synchronization and any of those accesses uses a non-const member function of shared_ptr then a data race will occur unless all such access is performed through these functions, which are overloads of the corresponding atomic access functions (std::atomic_load, std::atomic_store, etc.).

Note that the control block of a shared_ptr is thread-safe: different std::shared_ptr objects can be accessed using mutable operations, such as operator= or reset, simultaneously by multiple threads, even when these instances are copies, and share the same control block internally.

1) Determines whether atomic access to the shared pointer pointed-to by p is lock-free.

2) Equivalent to atomic_load_explicit(p, std::memory_order_seq_cst).

3) Returns the shared pointer pointed-to by p.

As with the non-specialized std::atomic_load_explicit, if mo is std::memory_order_release or std::memory_order_acq_rel, the behavior is undefined.

4) Equivalent to atomic_store_explicit(p, r, std::memory_order_seq_cst).

5) Stores the shared pointer r in the shared pointer pointed-to by p atomically, as if by p->swap(r).

As with the non-specialized std::atomic_store_explicit, if mo is std::memory_order_release or std::memory_order_acq_rel, the behavior is undefined.

6) Equivalent to atomic_exchange_explicit(p, r, std::memory_order_seq_cst).

7) Stores the shared pointer r in the shared pointer pointed to by p and returns the value formerly pointed-to by p, atomically, as if by p->swap(r) and returns a copy of r after the swap.

8) Equivalent to

atomic_compare_exchange_weak_explicit
(p, expected, desired, std::memory_order_seq_cst,
std::memory_order_seq_cst).

9) Equivalent to

atomic_compare_exchange_strong_explicit
(p, expected, desired, std::memory_order_seq_cst,
std::memory_order_seq_cst).

10,11) Compares the shared pointers pointed-to by p and expected.

If they are equivalent (store the same pointer value, and either share ownership of the same object or are both empty), assigns desired into *p using the memory ordering constraints specified by success and returns true.
If they are not equivalent, assigns *p into *expected using the memory ordering constraints specified by failure and returns false.

atomic_compare_exchange_weak_explicit may fail spuriously.

If expected is a null pointer, or failure is std::memory_order_release or std::memory_order_acq_rel, the behavior is undefined.

If p is a null pointer, the behaviors of these functions are all undefined.

These functions were deprecated in favor of the specializations of the std::atomic template: std::atomic<std::shared_ptr> and std::atomic<std::weak_ptr>.	(since C++20) (until C++26)
These functions were removed in favor of the specializations of the std::atomic template: std::atomic<std::shared_ptr> and std::atomic<std::weak_ptr>.	(since C++26)

[edit] Example

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 2172	C++11	expected could be a null pointer	the behavior is undefined in this case
LWG 2980	C++11	empty `shared_ptr`s were never equivalent	equivalent if they store the same pointer value

[edit] See also

atomic_is_lock_free (C++11)	checks if the atomic type's operations are lock-free (function template) [edit]
atomic_storeatomic_store_explicit (C++11)(C++11)	atomically replaces the value of the atomic object with a non-atomic argument (function template) [edit]
atomic_loadatomic_load_explicit (C++11)(C++11)	atomically obtains the value stored in an atomic object (function template) [edit]
atomic_exchangeatomic_exchange_explicit (C++11)(C++11)	atomically replaces the value of the atomic object with non-atomic argument and returns the old value of the atomic (function template) [edit]
atomic_compare_exchange_weakatomic_compare_exchange_weak_explicitatomic_compare_exchange_strongatomic_compare_exchange_strong_explicit (C++11)(C++11)(C++11)(C++11)	atomically compares the value of the atomic object with non-atomic argument and performs atomic exchange if equal or atomic load if not (function template) [edit]

@@ Line 1: / Line 1: @@
-{{cpp/title | atomic_...{{dsc small|<std::shared_ptr>}}}}
+{{cpp/title|atomic_...{{dsc small|<std::shared_ptr>}}}}
 {{cpp/memory/shared_ptr/navbar}}
 {{dcl begin}}
-{{dcl | num=1 | notes={{mark since c++11}} | 1=
+{{dcl header|memory}}
+{{dcl|num=1|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
 bool atomic_is_lock_free( const std::shared_ptr<T>* p );
 }}
-{{dcl | num=2 | notes={{mark since c++11}} | 1=
+{{dcl|num=2|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
 std::shared_ptr<T> atomic_load( const std::shared_ptr<T>* p );
 }}
-{{dcl | num=3 | notes={{mark since c++11}} | 1=
+{{dcl|num=3|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
-std::shared_ptr<T> atomic_load_explicit( const shared_ptr<T>* p,
+std::shared_ptr<T> atomic_load_explicit
-                                         std::memory_order mo );
+    ( const std::shared_ptr<T>* p, std::memory_order mo );
 }}
-{{dcl | num=4 | notes={{mark since c++11}} | 1=
+{{dcl|num=4|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
-void atomic_store( std::shared_ptr<T>* p,
+void atomic_store( std::shared_ptr<T>* p, std::shared_ptr<T> r );
-                   std::shared_ptr<T> r );
 }}
-{{dcl | num=5 | notes={{mark since c++11}} | 1=
+{{dcl|num=5|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
-void atomic_store_explicit( std::shared_ptr<T>* p,
+void atomic_store_explicit
-                            shared_ptr<T> r,
+    ( std::shared_ptr<T>* p, std::shared_ptr<T> r,
-                            std::memory_order mo);
+      std::memory_order mo );
 }}
-{{dcl | num=6 | notes={{mark since c++11}} | 1=
+{{dcl|num=6|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
-std::shared_ptr<T> atomic_exchange( std::shared_ptr<T>* p,
+std::shared_ptr<T> atomic_exchange
-                                    std::shared_ptr<T> r);
+    ( std::shared_ptr<T>* p, std::shared_ptr<T> r );
 }}
-{{dcl | num=7 | notes={{mark since c++11}} | 1=
+{{dcl|num=7|since=c++11|deprecated=c++20|until=c++26|1=
-template<class T>
+template< class T >
-std::shared_ptr<T> atomic_exchange_explicit( std::shared_ptr<T>* p,
+std::shared_ptr<T> atomic_exchange_explicit
-                                             std::shared_ptr<T> r,
+    ( std::shared_ptr<T>* p, std::shared_ptr<T> r,
-                                             std::memory_order mo);
+      std::memory_order mo );
 }}
-{{dcl | num=8 | notes={{mark since c++11}} | 1=
+{{dcl|num=8|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
-bool atomic_compare_exchange_weak( std::shared_ptr<T>* p,
+bool atomic_compare_exchange_weak
-                                   std::shared_ptr<T>* expected,
+    ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected,
-                                   std::shared_ptr<T> desired);
+      std::shared_ptr<T> desired );
 }}
-{{dcl | num=9 | notes={{mark since c++11}} | 1=
+{{dcl|num=9|since=c++11|deprecated=c++20|until=c++26|1=
-template<class T>
+template< class T >
-bool atomic_compare_exchange_strong( std::shared_ptr<T>* p,
+bool atomic_compare_exchange_strong
-                                     std::shared_ptr<T>* expected,
+    ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected,
-                                     std::shared_ptr<T> desired);
+      std::shared_ptr<T> desired );
 }}
-{{dcl | num=10 | notes={{mark since c++11}} | 1=
+{{dcl|num=10|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
-bool atomic_compare_exchange_strong_explicit( std::shared_ptr<T>* p,
+bool atomic_compare_exchange_strong_explicit
-                                              std::shared_ptr<T>* expected,
+    ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected,
-                                              std::shared_ptr<T> desired,
+      std::shared_ptr<T> desired,
-                                              std::memory_order success,
+      std::memory_order success, std::memory_order failure );
-                                              std::memory_order failure);
 }}
-{{dcl | num=11 | notes={{mark since c++11}} | 1=
+{{dcl|num=11|since=c++11|deprecated=c++20|until=c++26|1=
 template< class T >
-bool atomic_compare_exchange_weak_explicit( std::shared_ptr<T>* p,
+bool atomic_compare_exchange_weak_explicit
-                                            std::shared_ptr<T>* expected,
+    ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected,
-                                            std::shared_ptr<T> desired,
+      std::shared_ptr<T> desired,
-                                            std::memory_order success,
+      std::memory_order success, std::memory_order failure );
-                                            std::memory_order failure);
 }}
 {{dcl end}}
-If multiple threads of execution access the object referenced by the same {{lc|std::shared_ptr}} without synchronization, a data race may occur, unless all such access is performed through these functions, which are partial specializations of the corresponding atomic access functions ({{lc|std::atomic_load}}, {{lc|std::atomic_store}}, etc)
+If multiple threads of execution access the same {{lc|std::shared_ptr}} object without synchronization and any of those accesses uses a non-const member function of {{tt|shared_ptr}} then a data race will occur unless all such access is performed through these functions, which are overloads of the corresponding atomic access functions ({{lc|std::atomic_load}}, {{lc|std::atomic_store}}, etc.).
-Note that the control block of a shared_ptr is thread-safe: different {{lc|std::shared_ptr}} objects can be accessed using mutable operations, such as operator= or reset, simultaneously by multiple threads, even when these instances are copies, and share the same control block internally.
+Note that the control block of a {{tt|shared_ptr}} is thread-safe: different {{lc|std::shared_ptr}} objects can be accessed using mutable operations, such as {{c/core|1=operator=}} or {{tt|reset}}, simultaneously by multiple threads, even when these instances are copies, and share the same control block internally.
-@1@ Determines whether atomic access to the shared pointer pointed-to by {{tt|p}} is lock-free.
+@1@ Determines whether atomic access to the shared pointer pointed-to by {{c|p}} is lock-free.
-@2@ Equivalent to {{c|atomic_load_explicit(p, std::memory_order_seq_cst)}}
-@3@ Returns the shared pointer pointed-to by {{tt|p}}. As with the non-specialized {{lc|std::atomic_load_explicit}}, {{tt|mo}} cannot be {{lc|std::memory_order_release}} or {{lc|std::memory_order_acq_rel}}
-@4@ Equivalent to {{c|atomic_store_explicit(p, r, memory_order_seq_cst)}}
-@5@ Swaps the shared pointers {{tt|p}} and {{tt|r}}, effectively executing {{c|p->swap(r)}}. As with the non-specialized {{lc|std::atomic_store_explicit}}, {{tt|mo}} cannot be {{lc|std::memory_order_acquire}} or {{lc|std::memory_order_acq_rel}}
-@6@ Equivalent to {{c|atomic_exchange_explicit(p, r, memory_order_seq_cst)}}
-@7@ Swaps the shared pointers {{tt|p}} and {{tt|r}}, effectively executing {{c|p->swap(r)}} and returns a copy of the shared pointer formerly pointed-to by {{tt|p}}
-@8@ Equivalent to {{c|atomic_compare_exchange_weak_explicit(p, expected, desired, std::memory_order_seq_cst, std::memory_order_seq_cst)}}
-@9@ Equivalent to {{c|atomic_compare_exchange_strong_explicit(p, expected, desired, std::memory_order_seq_cst, std::memory_order_seq_cst)}}
-@10@ Compares the shared pointers pointed-to by {{tt|p}} and {{tt|expected}}. If they are equivalent (share ownership of the same pointer and refer to the same pointer), assigns {{tt|desired}} into {{tt|*p}} using the memory ordering constraints specified by {{tt|success}} and returns {{c|true}}. If they are not equivalent, assigns {{tt|*p}} into {{tt|*expected}} using the memory ordering constraints specified by {{tt|failure}} and returns {{c|false}}.
-@11@ Same as 10), but may fail spuriously.
-All these functions invoke undefined behavior if {{tt|p}} is a null pointer.
+@2@ Equivalent to {{c|atomic_load_explicit(p, std::memory_order_seq_cst)}}.
+@3@ Returns the shared pointer pointed-to by {{c|p}}.
+@@ As with the non-specialized {{lc|std::atomic_load_explicit}}, if {{c|mo}} is {{c|std::memory_order_release}} or {{c|std::memory_order_acq_rel}}, the behavior is undefined.
+@4@ Equivalent to {{c|atomic_store_explicit(p, r, std::memory_order_seq_cst)}}.
+@5@ Stores the shared pointer {{c|r}} in the shared pointer pointed-to by {{c|p}} atomically, {{lt|cpp/language/as if}} by {{c|p->swap(r)}}.
+@@ As with the non-specialized {{lc|std::atomic_store_explicit}}, if {{c|mo}} is {{c|std::memory_order_release}} or {{c|std::memory_order_acq_rel}}, the behavior is undefined.
+@6@ Equivalent to {{c|atomic_exchange_explicit(p, r, std::memory_order_seq_cst)}}.
+@7@ Stores the shared pointer {{c|r}} in the shared pointer pointed to by {{c|p}} and returns the value formerly pointed-to by {{c|p}}, atomically, {{lt|cpp/language/as if}} by {{c|p->swap(r)}} and returns a copy of {{c|r}} after the swap.
+@8@ Equivalent to
+@@ {{c multi
+|atomic_compare_exchange_weak_explicit
+|    (p, expected, desired, std::memory_order_seq_cst,
+|                           std::memory_order_seq_cst)}}.
+@9@ Equivalent to
+@@ {{c multi
+|atomic_compare_exchange_strong_explicit
+|    (p, expected, desired, std::memory_order_seq_cst,
+|                           std::memory_order_seq_cst)}}.
+@10,11@ Compares the shared pointers pointed-to by {{c|p}} and {{c|expected}}.
+* If they are equivalent (store the same pointer value, and either share ownership of the same object or are both empty), assigns {{c|desired}} into {{c|*p}} using the memory ordering constraints specified by {{c|success}} and returns {{c|true}}.
+* If they are not equivalent, assigns {{c|*p}} into {{c|*expected}} using the memory ordering constraints specified by {{c|failure}} and returns {{c|false}}.
+@@ {{tt|atomic_compare_exchange_weak_explicit}} may fail spuriously.
+@@ If {{c|expected}} is a null pointer, or {{c|failure}} is {{c|std::memory_order_release}} or {{c|std::memory_order_acq_rel}}, the behavior is undefined.
+If {{c|p}} is a null pointer, the behaviors of these functions are all undefined.
 ===Parameters===
 {{par begin}}
-{{par | p, expected | a pointer to a {{lc|std::shared_ptr}} }}
+{{par|p, expected|a pointer to a {{lc|std::shared_ptr}}}}
-{{par | r, desired | a {{lc|std::shared_ptr}} }}
+{{par|r, desired|a {{lc|std::shared_ptr}}}}
-{{par | mo, success, failure | memory ordering selectors of type {{lc|std::memory_order}} }}
+{{par|mo, success, failure|memory ordering selectors of type {{lc|std::memory_order}}}}
 {{par end}}
@@ Line 96: / Line 117: @@
 ===Return value===
-@1@ {{c|true}} if atomic access is implemented using lock-free instructions
+@1@ {{c|true}} if atomic access is implemented using lock-free instructions.
 @2,3@ A copy of the pointed-to shared pointer.
 @4,5@ (none)
-@6,7@ A copy of the formerly pointed-to shared pointer
+@6,7@ A copy of the formerly pointed-to shared pointer.
-@8,9,10,11@ {{c|true}} if the shared pointers were equivalent and the exchange was performed, {{c|false}} otherwise.
+@8-11@ {{c|true}} if the shared pointers were equivalent and the exchange was performed, {{c|false}} otherwise.
+===Notes===
+These functions are typically implemented using mutexes, stored in a global hash table where the pointer value is used as the key.
+The [[cpp/experimental/concurrency|Concurrency TS]] offers atomic smart pointer classes {{tt|atomic_shared_ptr}} and {{tt|atomic_weak_ptr}} as a replacement for the use of these functions.
+{{rrev multi|since1=c++20|until1=c++26|rev1=
+These functions were deprecated in favor of the specializations of the {{lc|std::atomic}} template: {{c/core|std::atomic<std::shared_ptr>}} and {{c/core|std::atomic<std::weak_ptr>}}.
+|rev2=
+These functions were removed in favor of the specializations of the {{lc|std::atomic}} template: {{c/core|std::atomic<std::shared_ptr>}} and {{c/core|std::atomic<std::weak_ptr>}}.
+}}
 ===Example===
 {{example}} <!-- adapt from http://stackoverflow.com/a/16617935/273767 -->
+===Defect reports===
+{{dr list begin}}
+{{dr list item|wg=lwg|dr=2172|std=C++11|before={{c|expected}} could be a null pointer|after=the behavior is undefined in this case}}
+{{dr list item|wg=lwg|dr=2980|std=C++11|before=empty {{tt|shared_ptr}}s were never equivalent|after=equivalent if they store the same pointer value}}
+{{dr list end}}
 ===See also===
 {{dsc begin}}
-{{dsc inc | cpp/atomic/dsc atomic_is_lock_free}}
+{{dsc inc|cpp/atomic/dsc atomic_is_lock_free}}
-{{dsc inc | cpp/atomic/dsc atomic_store}}
+{{dsc inc|cpp/atomic/dsc atomic_store}}
-{{dsc inc | cpp/atomic/dsc atomic_load}}
+{{dsc inc|cpp/atomic/dsc atomic_load}}
-{{dsc inc | cpp/atomic/dsc atomic_exchange}}
+{{dsc inc|cpp/atomic/dsc atomic_exchange}}
-{{dsc inc | cpp/atomic/dsc atomic_compare_exchange}}
+{{dsc inc|cpp/atomic/dsc atomic_compare_exchange}}
 {{dsc end}}
-[[de:cpp/memory/shared ptr/atomic]]
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
-[[es:cpp/memory/shared ptr/atomic]]
-[[fr:cpp/memory/shared ptr/atomic]]
-[[it:cpp/memory/shared ptr/atomic]]
-[[ja:cpp/memory/shared ptr/atomic]]
-[[pt:cpp/memory/shared ptr/atomic]]
-[[ru:cpp/memory/shared ptr/atomic]]
-[[zh:cpp/memory/shared ptr/atomic]]

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Member functions
shared_ptr::shared_ptr
shared_ptr::~shared_ptr
shared_ptr::operator=
Modifiers
shared_ptr::reset
shared_ptr::swap
Observers
shared_ptr::get
shared_ptr::operator*shared_ptr::operator->
shared_ptr::operator[] (C++17)
shared_ptr::use_count
shared_ptr::unique (until C++20*)
shared_ptr::operator bool
shared_ptr::owner_before
shared_ptr::owner_hash (C++26)
shared_ptr::owner_equal (C++26)
Non-member functions
swap(std::shared_ptr)
make_sharedmake_shared_for_overwrite (C++20)
allocate_sharedallocate_shared_for_overwrite (C++20)
static_pointer_castdynamic_pointer_castconst_pointer_castreinterpret_pointer_cast (C++17)
get_deleter
operator==operator!=operator<operator<=operator>operator>=operator<=> (until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
operator<<
atomic_xxx functions (until C++26*)
Helper classes
atomic<std::shared_ptr> (C++20)
hash<std::shared_ptr>
Deduction guides(C++17)

p, expected	-	a pointer to a std::shared_ptr
r, desired	-	a std::shared_ptr
mo, success, failure	-	memory ordering selectors of type std::memory_order

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/memory/shared ptr/atomic"

Latest revision as of 23:04, 20 October 2024

Contents

[edit] Parameters

[edit] Exceptions

[edit] Return value

[edit] Notes

[edit] Example

[edit] Defect reports

[edit] See also

Navigation

Toolbox