std::atomic

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

Atomic operations library

Types

atomic (C++11)

atomic_is_lock_free (C++11)

Functions

atomic_store atomic_store_explicit (C++11) (C++11)

atomic_load atomic_load_explicit (C++11) (C++11)

atomic_exchange atomic_exchange_explicit (C++11) (C++11)

atomic_compare_exchange_weak atomic_compare_exchange_weak_explicit atomic_compare_exchange_strong atomic_compare_exchange_strong_explicit (C++11) (C++11) (C++11) (C++11)

atomic_fetch_add atomic_fetch_add_explicit (C++11) (C++11)

atomic_fetch_sub atomic_fetch_sub_explicit (C++11) (C++11)

atomic_fetch_and atomic_fetch_and_explicit (C++11) (C++11)

atomic_fetch_or atomic_fetch_or_explicit (C++11) (C++11)

atomic_fetch_xor atomic_fetch_xor_explicit (C++11) (C++11)

Atomic flags

atomic_flag (C++11)

atomic_flag_test_and_set atomic_flag_test_and_set_explicit (C++11) (C++11)

atomic_flag_clear atomic_flag_clear_explicit (C++11) (C++11)

Initialization

atomic_init (C++11)

ATOMIC_VAR_INIT (C++11)

ATOMIC_FLAG_INIT (C++11)

Memory ordering

memory_order (C++11)

kill_dependency (C++11)

atomic_thread_fence (C++11)

atomic_signal_fence (C++11)

 

std::atomic

Member functions

atomic::atomic

atomic::operator=

atomic::is_lock_free

atomic::store

atomic::load

atomic::operator T

atomic::exchange

atomic::compare_exchange

Specialized member functions

atomic::fetch_add

atomic::fetch_sub

atomic::fetch_and

atomic::fetch_or

atomic::fetch_xor

atomic::operator++ atomic::operator++(int) atomic::operator-- atomic::operator--(int)

atomic::operator+= atomic::operator-= atomic::operator&= atomic::operator|= atomic::operator^=

 

Defined in header <atomic>
template< class T > struct atomic;	(1)	(since C++11)
template<> struct atomic<Integral>;	(2)	(since C++11)
template< class T > struct atomic<T*>;	(3)	(since C++11)

Each instantiation and full specialization of the std::atomic template defines an atomic type. Objects of atomic types are the only C++ objects that are free from data races; that is, if one thread writes to an atomic object while another thread reads from it, the behavior is well-defined.

In addition, accesses to atomic objects may establish inter-thread synchronization and order non-atomic memory accesses as specified by std::memory_order.

The standard library provides specializations of the std::atomic template for the following types:

1) One full specialization for the type bool and its typedef name is defined that is treated as a non-specialized std::atomic<T> except that it has standard layout, trivial default constructor, trivial destructors, and supports aggregate initialization syntax:

Typedef name	Full specialization
std::atomic_bool	std::atomic<bool>

2) Full specializations and typedefs for integral types, as follows:

Typedef name	Full specialization
std::atomic_char	std::atomic<char>
std::atomic_schar	std::atomic<signed char>
std::atomic_uchar	std::atomic<unsigned char>
std::atomic_short	std::atomic<short>
std::atomic_ushort	std::atomic<unsigned short>
std::atomic_int	std::atomic<int>
std::atomic_uint	std::atomic<unsigned int>
std::atomic_long	std::atomic<long>
std::atomic_ulong	std::atomic<unsigned long>
std::atomic_llong	std::atomic<long long>
std::atomic_ullong	std::atomic<unsigned long long>
std::atomic_char16_t	std::atomic<char16_t>
std::atomic_char32_t	std::atomic<char32_t>
std::atomic_wchar_t	std::atomic<wchar_t>
std::atomic_int_least8_t	std::atomic<int_least8_t>
std::atomic_uint_least8_t	std::atomic<uint_least8_t>
std::atomic_int_least16_t	std::atomic<int_least16_t>
std::atomic_uint_least16_t	std::atomic<uint_least16_t>
std::atomic_int_least32_t	std::atomic<int_least32_t>
std::atomic_uint_least32_t	std::atomic<uint_least32_t>
std::atomic_int_least64_t	std::atomic<int_least64_t>
std::atomic_uint_least64_t	std::atomic<uint_least64_t>
std::atomic_int_fast8_t	std::atomic<int_fast8_t>
std::atomic_uint_fast8_t	std::atomic<uint_fast8_t>
std::atomic_int_fast16_t	std::atomic<int_fast16_t>
std::atomic_uint_fast16_t	std::atomic<uint_fast16_t>
std::atomic_int_fast32_t	std::atomic<int_fast32_t>
std::atomic_uint_fast32_t	std::atomic<uint_fast32_t>
std::atomic_int_fast64_t	std::atomic<int_fast64_t>
std::atomic_uint_fast64_t	std::atomic<uint_fast64_t>
std::atomic_intptr_t	std::atomic<intptr_t>
std::atomic_uintptr_t	std::atomic<uintptr_t>
std::atomic_size_t	std::atomic<size_t>
std::atomic_ptrdiff_t	std::atomic<ptrdiff_t>
std::atomic_intmax_t	std::atomic<intmax_t>
std::atomic_uintmax_t	std::atomic<uintmax_t>

These specializations have standard layout, trivial default constructors, and trivial destructors. They support aggregate initialization syntax.

3) Partial specializations std::atomic<T*> for all pointer types. These specializations have standard layout, trivial default constructors, and trivial destructors. They support aggregate initialization syntax.

In addition, std::atomic may be instantiated with any TriviallyCopyable type T.

Member functions

(constructor)	constructs an atomic object (public member function)
operator=	stores a value into an atomic object (public member function)
is_lock_free	checks if the atomic object is lock-free (public member function)
store (C++11)	atomically replaces the value of the atomic object with a non-atomic argument (public member function)
load (C++11)	atomically obtains the value of the atomic object (public member function)
operator T	loads a value from an atomic object (public member function)
exchange (C++11)	atomically replaced the value of the atomic object and obtains the value held previously (public member function)
compare_exchange_weak compare_exchange_strong	atomically compares the value of the atomic object with non-atomic argument and performs atomic exchange if equal or atomic load if not (public member function)

Specialized member functions

fetch_add (C++11)	atomically adds the argument to the value stored in the atomic object and obtains the value held previously (public member function)
fetch_sub (C++11)	atomically subtracts the argument from the value stored in the atomic object and obtains the value held previously (public member function)
fetch_and (C++11)	atomically performs bitwise AND between the argument and the value of the atomic object and obtains the value held previously (public member function)
fetch_or (C++11)	atomically performs bitwise OR between the argument and the value of the atomic object and obtains the value held previously (public member function)
fetch_xor (C++11)	atomically performs bitwise XOR between the argument and the value of the atomic object and obtains the value held previously (public member function)
operator++ operator++(int) operator-- operator--(int)	increments or decrements the atomic value by one (public member function)
operator+= operator-= operator&= operator|= operator^=	adds, subtracts, or performs bitwise AND, OR, XOR with the atomic value (public member function)

Notes

There are non-member function template equivalents for all member functions of std::atomic. Those non-member functions may be additionally overloaded for types that are not specializations of std::atomic, but are able to guarantee atomicity. The only such type in the standard library is std::shared_ptr<T>.

See also

atomic_flag (C++11)	the lock-free boolean atomic type (class)