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

NAME
     std::atomic_ref - std::atomic_ref

Synopsis
	Defined in header <atomic>
	template< class T >	   (1) (since C++20)
	struct atomic_ref;
	template< class T >	   (2) (since C++20)
	struct atomic_ref<T*>;

	The  std::atomic_ref class template applies atomic operations to the ob-
     ject it
	references. For the lifetime of the std::atomic_ref object,  the  object
     it references
	is considered an atomic object. If one thread writes to an atomic object
     while
	another  thread  reads from it, the behavior is well-defined (see memory
     model for
	details on data races). In addition, accesses to atomic objects may  es-
     tablish
	inter-thread  synchronization  and  order  non-atomic memory accesses as
     specified by
	std::memory_order.

	The  lifetime  of  an  object  must   exceed   the   lifetime	of   all
     std::atomic_refs that
	references the object. While any std::atomic_ref instance referencing an
     object
	exists,   the	object	 must  be  exclusively	accessed  through  these
     std::atomic_ref
	instances. No subobject of an object referenced  by  an  std::atomic_ref
     object may be
	concurrently referenced by any other std::atomic_ref object.

	Atomic	operations  applied  to an object through an std::atomic_ref are
     atomic with
	respect to atomic operations applied through any  other  std::atomic_ref
     referencing
	the same object.

	std::atomic_ref is CopyConstructible.

	Like  language references, constness is shallow for std::atomic_ref - it
     is possible
	to modify the referenced value through a const std::atomic_ref object.

Specializations
	  Primary template

	The primary std::atomic_ref template may be instantiated with any  Triv-
     iallyCopyable
	type T (including bool):

      struct Counters { int a; int b; }; // user-defined trivially-copyable type
      alignas(std::atomic_ref<Counters>::required_alignment) Counters counter;
      std::atomic_ref<Counters> cnt(counter); // specialization for the user-de-
     fined type

	  Partial specialization for pointer types

	The   standard	 library   provides   partial	specializations  of  the
     std::atomic_ref
	template for all pointer types. In addition to the  operations	provided
     for all
	atomic	types,	these specializations additionally support atomic arith-
     metic
	operations appropriate to pointer types, such as fetch_add, fetch_sub.

	  Specializations for integral types

	When  instantiated  with  one	of   the   following   integral   types,
     std::atomic_ref provides
	additional  atomic  operations	appropriate  to  integral  types such as
     fetch_add,
	fetch_sub, fetch_and, fetch_or, fetch_xor:

	  * The character types char, char8_t, char16_t, char32_t, and wchar_t;
	  * The standard signed integer types: signed char,  short,  int,  long,
     and long long;
	  *  The standard unsigned integer types: unsigned char, unsigned short,
     unsigned
	    int, unsigned long, and unsigned long long;
	  * Any additional integral types needed by the typedefs in  the  header
     <cstdint>.

	Signed	integer arithmetic is defined to use two's complement; there are
     no undefined
	results.

	  Specializations for floating-point types

	When instantiated with one of the  cv-unqualified  floating-point  types
     (float,
	double, long double
	and cv-unqualified extended floating-point types
	(since	C++23)),  std::atomic_ref  provides additional atomic operations
     appropriate to
	floating-point types such as fetch_add and fetch_sub.

	No operations result in undefined behavior even if  the  result  is  not
     representable
	in the floating-point type. The floating-point environment in effect may
     be
	different from the calling thread's floating-point environment.

Member types
	Member type	Definition
	value_type	see below
			value_type    (only    for    atomic_ref<Integral>   and
     atomic_ref<Floating>
	difference_type specializations)
			std::ptrdiff_t (only for std::atomic_ref<T*> specializa-
     tions)

	For every std::atomic_ref<X> (whether or not specialized),
	std::atomic_ref<X>::value_type is X.

	difference_type is not defined in the primary atomic_ref template.

Member functions
	constructor		constructs an atomic_ref object
				(public member function)
				stores a value into the object referenced by  an
     atomic_ref
	operator=		object
				(public member function)
	is_lock_free		checks if the atomic_ref object is lock-free
				(public member function)
				atomically  replaces the value of the referenced
     object with
	store			a non-atomic argument
				(public member function)
	load			atomically obtains the value of  the  referenced
     object
				(public member function)
	operator T		loads a value from the referenced object
				(public member function)
				atomically  replaces the value of the referenced
     object and
	exchange		obtains the value held previously
				(public member function)
				atomically compares the value of the  referenced
     object with
	compare_exchange_weak	non-atomic argument and performs atomic exchange
     if equal or
	compare_exchange_strong atomic load if not
				(public member function)
				blocks	the thread until notified and the atomic
     value
	wait			changes
				(public member function)
	notify_one		notifies at least  one	thread	waiting  on  the
     atomic object
				(public member function)
	notify_all		 notifies  all	threads  blocked  waiting on the
     atomic object
				(public member function)

Constants
	is_always_lock_free	indicates that the type is always lock-free
	[static]		(public static member constant)
	required_alignment	indicates the required alignment of an object to
     be
	[static]		referenced by atomic_ref
				(public static member constant)

Specialized member functions
	      Specialized for integral, floating-point and pointer types
			atomically adds the argument to the value stored in  the
     referenced
	fetch_add	object and obtains the value held previously
			(public member function)
			atomically  subtracts the argument from the value stored
     in the
	fetch_sub	referenced object and obtains the value held previously
			(public member function)
	operator+=	atomically adds to  or	subtracts  from  the  referenced
     value
	operator-=	(public member function)
	      Specialized for integral and pointer types only
	fetch_max	 atomically  performs  std::max between the argument and
     the value of
	(C++26) 	the referenced object and obtains the value held  previ-
     ously
			(public member function)
	fetch_min	 atomically  performs  std::min between the argument and
     the value of
	(C++26) 	the referenced object and obtains the value held  previ-
     ously
			(public member function)
	operator++
	operator++(int)  atomically  increments or decrements the referenced ob-
     ject by one
	operator--	(public member function)
	operator--(int)
	      Specialized for integral types only
			atomically performs bitwise AND between the argument and
     the value
	fetch_and	of the referenced object and obtains the value held pre-
     viously
			(public member function)
			atomically performs bitwise OR between the argument  and
     the value of
	fetch_or	 the referenced object and obtains the value held previ-
     ously
			(public member function)
			atomically performs bitwise XOR between the argument and
     the value
	fetch_xor	of the referenced object and obtains the value held pre-
     viously
			(public member function)
	operator&=	atomically performs bitwise AND, OR, XOR with the refer-
     enced value
	operator|=	(public member function)
	operator^=

Notes
	 Feature-test macro   Value    Std	 Feature
	__cpp_lib_atomic_ref 201806L (C++20) std::atomic_ref

See also
		atomic class template and specializations for bool, integral,
	atomic	floating-point,
	(C++11) (since C++20) and pointer types
		(class template)

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