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)

Filesystem library (C++17)

Technical Specifications

 

Atomic operations library

Types

atomic (C++11)

atomic_is_lock_free (C++11)

Functions

atomic_storeatomic_store_explicit (C++11)(C++11)

atomic_loadatomic_load_explicit (C++11)(C++11)

atomic_exchangeatomic_exchange_explicit (C++11)(C++11)

atomic_compare_exchange_weakatomic_compare_exchange_weak_explicitatomic_compare_exchange_strongatomic_compare_exchange_strong_explicit (C++11)(C++11)(C++11)(C++11)

atomic_fetch_addatomic_fetch_add_explicit (C++11)(C++11)

atomic_fetch_subatomic_fetch_sub_explicit (C++11)(C++11)

atomic_fetch_andatomic_fetch_and_explicit (C++11)(C++11)

atomic_fetch_oratomic_fetch_or_explicit (C++11)(C++11)

atomic_fetch_xoratomic_fetch_xor_explicit (C++11)(C++11)

Atomic flags

atomic_flag (C++11)

atomic_flag_test_and_setatomic_flag_test_and_set_explicit (C++11)(C++11)

atomic_flag_clearatomic_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<> struct atomic<bool>;	(3)	(since C++11)
template< class T > struct atomic<T*>;	(4)	(since C++11)

Each instantiation and full specialization of the std::atomic template defines an atomic type. 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 establish inter-thread synchronization and order non-atomic memory accesses as specified by std::memory_order.

std::atomic may be instantiated with any TriviallyCopyable type T. std::atomic is neither copyable nor movable.

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_int8_t	std::atomic<std::int8_t>
std::atomic_uint8_t	std::atomic<std::uint8_t>
std::atomic_int16_t	std::atomic<std::int16_t>
std::atomic_uint16_t	std::atomic<std::uint16_t>
std::atomic_int32_t	std::atomic<std::int32_t>
std::atomic_uint32_t	std::atomic<std::uint32_t>
std::atomic_int64_t	std::atomic<std::int64_t>
std::atomic_uint64_t	std::atomic<std::uint64_t>
std::atomic_int_least8_t	std::atomic<std::int_least8_t>
std::atomic_uint_least8_t	std::atomic<std::uint_least8_t>
std::atomic_int_least16_t	std::atomic<std::int_least16_t>
std::atomic_uint_least16_t	std::atomic<std::uint_least16_t>
std::atomic_int_least32_t	std::atomic<std::int_least32_t>
std::atomic_uint_least32_t	std::atomic<std::uint_least32_t>
std::atomic_int_least64_t	std::atomic<std::int_least64_t>
std::atomic_uint_least64_t	std::atomic<std::uint_least64_t>
std::atomic_int_fast8_t	std::atomic<std::int_fast8_t>
std::atomic_uint_fast8_t	std::atomic<std::uint_fast8_t>
std::atomic_int_fast16_t	std::atomic<std::int_fast16_t>
std::atomic_uint_fast16_t	std::atomic<std::uint_fast16_t>
std::atomic_int_fast32_t	std::atomic<std::int_fast32_t>
std::atomic_uint_fast32_t	std::atomic<std::uint_fast32_t>
std::atomic_int_fast64_t	std::atomic<std::int_fast64_t>
std::atomic_uint_fast64_t	std::atomic<std::uint_fast64_t>
std::atomic_intptr_t	std::atomic<std::intptr_t>
std::atomic_uintptr_t	std::atomic<std::uintptr_t>
std::atomic_size_t	std::atomic<std::size_t>
std::atomic_ptrdiff_t	std::atomic<std::ptrdiff_t>
std::atomic_intmax_t	std::atomic<std::intmax_t>
std::atomic_uintmax_t	std::atomic<std::uintmax_t>

Note: std::atomic_intN_t, std::atomic_uintN_t, std::atomic_intptr_t, and atomic_uintptr_t are defined if and only if std::intN_t, std::uintN_t, std::intptr_t, and std::uintptr_t are defined, respectively.

These specializations have standard layout, trivial default constructors, and trivial destructors. They support aggregate initialization syntax. Besides the operations provided for all atomic types, these specializations have additional atomic operations appropriate to integer types such as fetch_add, fetch_sub, fetch_and, fetch_or, fetch_xor.

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. Besides the operations provided for all atomic types, these specializations additionally support atomic arithmetic operations appropriate to pointer types, such as fetch_add, fetch_sub.

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	atomically replaces the value of the atomic object with a non-atomic argument (public member function)
load	atomically obtains the value of the atomic object (public member function)
operator T	loads a value from an atomic object (public member function)
exchange	atomically replaces the value of the atomic object and obtains the value held previously (public member function)
compare_exchange_weakcompare_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)
Constants
is_always_lock_free [static] (C++17)	indicates that the type is always lock-free (public static member constant)

Specialized member functions

fetch_add	atomically adds the argument to the value stored in the atomic object and obtains the value held previously (public member function)
fetch_sub	atomically subtracts the argument from the value stored in the atomic object and obtains the value held previously (public member function)
fetch_and	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	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	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>.

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 2441	c++11		added specializations for the (optional) fixed width integer types

See also

atomic_flag (C++11)

the lock-free boolean atomic type (class)

References

• C++11 standard (ISO/IEC 14882:2011):

• 29.5 Atomic types [atomics.types.generic]