home | help 
std::atomic_...(3)	       C++ Standard Libary	      std::atomic_...(3)

NAME
     std::atomic_... - std::atomic_...

Synopsis
	Defined in header <memory>
									 (since
     C++11)
	template< class T >					    (1)  (depre-
     cated in
	bool atomic_is_lock_free( const std::shared_ptr<T>* p );	 C++20)
									 (re-
     moved in C++26)
	template<  class T >						  (since
     C++11)
	std::shared_ptr<T> atomic_load( const std::shared_ptr<T>* p (2)  (depre-
     cated in
	);								 C++20)
									 (re-
     moved in C++26)
	template< class T >						  (since
     C++11)
									 (depre-
     cated in
	std::shared_ptr<T> atomic_load_explicit 		    (3)  C++20)
									 (re-
     moved in C++26)
	    ( const std::shared_ptr<T>* p, std::memory_order mo );
	template<  class T >						  (since
     C++11)
	void atomic_store( std::shared_ptr<T>* p,		    (4)  (depre-
     cated in
	std::shared_ptr<T> r ); 					 C++20)
									 (re-
     moved in C++26)
	template< class T >
									 (since
     C++11)
	void atomic_store_explicit				    (5)  (depre-
     cated in
	    ( std::shared_ptr<T>* p, std::shared_ptr<T> r,		 C++20)
									 (re-
     moved in C++26)
	      std::memory_order mo );
	template< class T >						  (since
     C++11)
									 (depre-
     cated in
	std::shared_ptr<T> atomic_exchange			    (6)  C++20)
									 (re-
     moved in C++26)
	    ( std::shared_ptr<T>* p, std::shared_ptr<T> r );
	template< class T >
									 (since
     C++11)
	std::shared_ptr<T> atomic_exchange_explicit		    (7)  (depre-
     cated in
	    ( std::shared_ptr<T>* p, std::shared_ptr<T> r,		 C++20)
									 (re-
     moved in C++26)
	      std::memory_order mo );
	template< class T >
									 (since
     C++11)
	bool atomic_compare_exchange_weak			    (8)  (depre-
     cated in
	    ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected,	 C++20)
									 (re-
     moved in C++26)
	      std::shared_ptr<T> desired );
	template< class T >
									 (since
     C++11)
	bool atomic_compare_exchange_strong			    (9)  (depre-
     cated in
	    ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected,	 C++20)
									 (re-
     moved in C++26)
	      std::shared_ptr<T> desired );
	template< class T >

	bool  atomic_compare_exchange_strong_explicit			  (since
     C++11)
	    ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected,  (10) (depre-
     cated in
	      std::shared_ptr<T> desired,				 C++20)
									 (re-
     moved in C++26)
	      std::memory_order success, std::memory_order failure
	);
	template< class T >

	bool atomic_compare_exchange_weak_explicit			  (since
     C++11)
	    ( std::shared_ptr<T>* p, std::shared_ptr<T>* expected,  (11) (depre-
     cated in
	      std::shared_ptr<T> desired,				 C++20)
									 (re-
     moved in C++26)
	      std::memory_order success, std::memory_order failure
	);

	If  multiple threads of execution access the same std::shared_ptr object
     without
	synchronization and any of those accesses uses a non-const member  func-
     tion of
	shared_ptr  then  a  data race will occur unless all such access is per-
     formed 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,
	equivalent to 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_or-
     der_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. Equivalent to 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 mem-
     ory 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  unde-
     fined.

Parameters
	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_or-
     der

Exceptions
	These functions do not throw exceptions.

Return value
	1) 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.
	8-11)  true  if the shared pointers were equivalent and the exchange was
     performed,
	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 Concurrency TS offers atomic smart pointer classes atomic_shared_ptr
     and
	atomic_weak_ptr as a replacement for the use of these functions.

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

Example
	 This section is incomplete
	 Reason: no example

	Defect reports

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

	   DR	 Applied to    Behavior as published		  Correct behav-
     ior
	LWG 2980 C++11	    empty shared_ptrs are never equivalent if they store
     the same
			    equivalent			pointer value

See also
	atomic_is_lock_free			 checks if the atomic type's op-
     erations are
	(C++11) 				lock-free
						(function template)
	atomic_store				atomically replaces the value of
     the atomic
	atomic_store_explicit			object with a  non-atomic  argu-
     ment
	(C++11) 				(function template)
	(C++11)
	atomic_load				 atomically  obtains  the  value
     stored in an
	atomic_load_explicit			atomic object
	(C++11) 				(function template)
	(C++11)
	atomic_exchange 			atomically replaces the value of
     the atomic
	atomic_exchange_explicit		object with non-atomic	argument
     and returns
	(C++11) 				the old value of the atomic
	(C++11) 				(function template)
	atomic_compare_exchange_weak
	atomic_compare_exchange_weak_explicit	atomically compares the value of
     the atomic
	atomic_compare_exchange_strong		 object with non-atomic argument
     and performs
	atomic_compare_exchange_strong_explicit  atomic  exchange  if  equal  or
     atomic load if
	(C++11) 				not
	(C++11) 				(function template)
	(C++11)
	(C++11)

Category:
	  * Todo no example

http://cppreference.com 	   2024.06.10		      std::atomic_...(3)
home | help