std::atomic - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::atomic

From cppreference.com
< cpp‎ | atomic

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.

`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_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>

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`.

### [edit] Member functions

(constructor) | constructs an atomic object (public member function) [edit]
operator= | stores a value into an atomic object (public member function) [edit]
is_lock_free | checks if the atomic object is lock-free (public member function) [edit]
store (C++11) | atomically replaces the value of the atomic object with a non-atomic argument (public member function) [edit]
load (C++11) | atomically obtains the value of the atomic object (public member function) [edit]
operator T | loads a value from an atomic object (public member function) [edit]
exchange (C++11) | atomically replaces the value of the atomic object and obtains the value held previously (public member function) [edit]
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) [edit]

### [edit] 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) [edit]
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) [edit]
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) [edit]
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) [edit]
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) [edit]
operator++operator++(int)operator--operator--(int) | increments or decrements the atomic value by one (public member function) [edit]
operator+=operator-=operator&=operator|=operator^= | adds, subtracts, or performs bitwise AND, OR, XOR with the atomic value (public member function) [edit]

### [edit] 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>.

### [edit] See also

atomic_flag (C++11) | the lock-free boolean atomic type (class) [edit]

### [edit] References

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

  - 29.5 Atomic types [atomics.types.generic]

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/atomic/atomic&oldid=81254"