Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

<atomic>

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at <atomic>.

Defines classes and template classes to use to create types that support atomic operations.

#include <atomic>  

System_CAPS_ICON_note.jpg Note

In code that's compiled by using /clr or /clr:pure, this header is blocked.

An atomic operation has two key properties that help you use multiple threads to correctly manipulate an object without using mutex locks.

  • Because an atomic operation is indivisible, a second atomic operation on the same object from a different thread can obtain the state of the object only before or after the first atomic operation.

  • Based on its memory_order argument, an atomic operation establishes ordering requirements for the visibility of the effects of other atomic operations in the same thread. Consequently, it inhibits compiler optimizations that violate the ordering requirements.

On some platforms, it might not be possible to efficiently implement atomic operations for some types without using mutex locks. An atomic type is lock-free if no atomic operations on that type use locks.

C++11: In signal-handlers you can perform atomic operations on an object obj if obj.is_lock_free() or atomic_is_lock_free(x) are true.

The class atomic_flag provides a minimal atomic type that holds a bool flag. Its operations are always lock-free.

The template class atomic<T> stores an object of its argument type T and provides atomic access to that stored value. You can instantiate it by using any type that can be copied by using memcpy and tested for equality by using memcmp. In particular, you can use it with user-defined types that meet these requirements and, in many cases, with floating-point types.

The template also has a set of specializations for integral types and a partial specialization for pointers. These specializations provide additional operations that are not available through the primary template.

The atomic<T *> partial specializations apply to all pointer types. They provide methods for pointer arithmetic.

The atomic<integral> specializations apply to all integral types. They provide additional operations that are not available through the primary template.

Each atomic<integral> type has a corresponding macro that you can use in an if directive to determine at compile time whether operations on that type are lock-free. If the value of the macro is zero, operations on the type are not lock-free. If the value is 1, operations might be lock-free, and a runtime check is required. If the value is 2, operations are lock-free. You can use the function atomic_is_lock_free to determine at runtime whether operations on the type are lock-free.

For each of the integral types, there is a corresponding named atomic type that manages an object of that integral type. Each atomic_integral type has the same set of member functions as the corresponding instantiation of atomic<T> and can be passed to any of the non-member atomic functions.

atomic_integral TypeIntegral Typeatomic_is_lock_free Macro
atomic_charcharATOMIC_CHAR_LOCK_FREE
atomic_scharsigned charATOMIC_CHAR_LOCK_FREE
atomic_ucharunsigned charATOMIC_CHAR_LOCK_FREE
atomic_char16_tchar16_tATOMIC_CHAR16_T_LOCK_FREE
atomic_char32_tchar32_tATOMIC_CHAR32_T_LOCK_FREE
atomic_wchar_twchar_tATOMIC_WCHAR_T_LOCK_FREE
atomic_shortshortATOMIC_SHORT_LOCK_FREE
atomic_ushortunsigned shortATOMIC_SHORT_LOCK_FREE
atomic_intintATOMIC_INT_LOCK_FREE
atomic_uintunsigned intATOMIC_INT_LOCK_FREE
atomic_longlongATOMIC_LONG_LOCK_FREE
atomic_ulongunsigned longATOMIC_LONG_LOCK_FREE
atomic_llonglong longATOMIC_LLONG_LOCK_FREE
atomic_ullongunsigned long longATOMIC_LLONG_LOCK_FREE

Typedef names exist for specializations of the atomic template for some of the types that are defined in the header <inttypes.h>.

Atomic TypeTypedef Name
atomic_int8_tatomic<int8_t>
atomic_uint8_tatomic<uint8_t>
atomic_int16_tatomic<int16_t>
atomic_uint16_tatomic<uint16_t>
atomic_int32_tatomic<int32_t>
atomic_uint32_tatomic<uint32_t>
atomic_int64_tatomic<int64_t>
atomic_uint64_tatomic<uint64_t>
atomic_int_least8_tatomic<int_least8_t>
atomic_uint_least8_tatomic<uint_least8_t>
atomic_int_least16_tatomic<int_least16_t>
atomic_uint_least16_tatomic<uint_least16_t>
atomic_int_least32_tatomic<int_least32_t>
atomic_uint_least32_tatomic<uint_least32_t>
atomic_int_least64_tatomic<int_least64_t>
atomic_uint_least64_tatomic<uint_least64_t>
atomic_int_fast8_tatomic<int_fast8_t>
atomic_uint_fast8_tatomic<uint_fast8_t>
atomic_int_fast16_tatomic<int_fast16_t>
atomic_uint_fast16_atomic<uint_fast16_t>
atomic_int_fast32_tatomic<int_fast32_t>
atomic_uint_fast32_tatomic<uint_fast32_t>
atomic_int_fast64_tatomic<int_fast64_t>
atomic_uint_fast64_tatomic<uint_fast64_t>
atomic_intptr_tatomic<intptr_t>
atomic_uintptr_tatomic<uintptr_t>
atomic_size_tatomic<size_t>
atomic_ptrdiff_tatomic<ptrdiff_t>
atomic_intmax_tatomic<intmax_t>
atomic_uintmax_tatomic<uintmax_t>
NameDescription
atomic StructureDescribes an object that performs atomic operations on a stored value.
atomic_flag StructureDescribes an object that atomically sets and clears a bool flag.
NameDescription
memory_order EnumSupplies symbolic names for synchronization operations on memory locations. These operations affect how assignments in one thread become visible in another.

In the following list, the functions that do not end in _explicit have the semantics of the corresponding _explicit, except that they have the implicit memory_order arguments of memory_order_seq_cst.

NameDescription
atomic_compare_exchange_strong FunctionPerforms an atomic compare and exchange operation.
atomic_compare_exchange_strong_explicit FunctionPerforms an atomic compare and exchange operation.
atomic_compare_exchange_weak FunctionPerforms a weak atomic compare and exchange operation.
atomic_compare_exchange_weak_explicit FunctionPerforms a weak atomic compare and exchange operation.
atomic_exchange FunctionReplaces a stored value.
atomic_exchange_explicit FunctionReplaces a stored value.
atomic_fetch_add FunctionAdds a specified value to an existing stored value.
atomic_fetch_add_explicit FunctionAdds a specified value to an existing stored value.
atomic_fetch_and FunctionPerforms a bitwise and on a specified value and an existing stored value.
atomic_fetch_and_explicit FunctionPerforms a bitwise and on a specified value and an existing stored value.
atomic_fetch_or FunctionPerforms a bitwise or on a specified value and an existing stored value.
atomic_fetch_or_explicit FunctionPerforms a bitwise or on a specified value and an existing stored value.
atomic_fetch_sub FunctionSubtracts a specified value from an existing stored value.
atomic_fetch_sub_explicit FunctionSubtracts a specified value from an existing stored value.
atomic_fetch_xor FunctionPerforms a bitwise exclusive or on a specified value and an existing stored value.
atomic_fetch_xor_explicit FunctionPerforms a bitwise exclusive or on a specified value and an existing stored value.
atomic_flag_clear FunctionSets the flag in an atomic_flag object to false.
atomic_flag_clear_explicit FunctionSets the flag in an atomic_flag object to false.
atomic_flag_test_and_set FunctionSets the flag in an atomic_flag object to true.
atomic_flag_test_and_set_explicit FunctionSets the flag in an atomic_flag object to true.
atomic_init FunctionSets the stored value in an atomic object.
atomic_is_lock_free FunctionSpecifies whether atomic operations on a specified object are lock-free.
atomic_load FunctionAtomically retrieves a value.
atomic_load_explicit FunctionAtomically retrieves a value.
atomic_signal_fence FunctionActs as a fence that establishes memory ordering requirements between fences in a calling thread that has signal handlers executed in the same thread.
atomic_store FunctionAtomically stores a value.
atomic_store_explicit FunctionAtomically stores a value.
atomic_thread_fence FunctionActs as a fence that establishes memory ordering requirements with respect to other fences.
kill_dependency FunctionBreaks a possible dependency chain.

Header Files Reference
Standard Template Library

Show:
© 2017 Microsoft