Partager via


<atomic> functions

 

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

atomic_compare_exchange_strong Function atomic_compare_exchange_strong_explicit Function atomic_compare_exchange_weak Function
atomic_compare_exchange_weak_explicit Function atomic_exchange Function atomic_exchange_explicit Function
atomic_fetch_add Function atomic_fetch_add_explicit Function atomic_fetch_and Function
atomic_fetch_and_explicit Function atomic_fetch_or Function atomic_fetch_or_explicit Function
atomic_fetch_sub Function atomic_fetch_sub_explicit Function atomic_fetch_xor Function
atomic_fetch_xor_explicit Function atomic_flag_clear Function atomic_flag_clear_explicit Function
atomic_flag_test_and_set Function atomic_flag_test_and_set_explicit Function atomic_init Function
atomic_is_lock_free Function atomic_load Function atomic_load_explicit Function
atomic_signal_fence Function atomic_store Function atomic_store_explicit Function
atomic_thread_fence Function kill_dependency Function

atomic_compare_exchange_strong Function

Performs an atomic compare and exchange operation.

template <class Ty>
inline bool atomic_compare_exchange_strong(
    volatile atomic<Ty>* Atom, Ty* Exp, Ty Value) noexcept;
template <class Ty>
inline bool atomic_compare_exchange_strong(
    atomic<Ty>* Atom, Ty* Exp, Ty Value) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a value of type Ty.

Exp
A pointer to a value of type Ty.

Value
A value of type Ty.

Return Value

A bool that indicates the result of the value comparison.

Remarks

This method performs an atomic compare and exchange operation by using implicit memory_order_seq_cstmemory_order arguments. For more information, see atomic_compare_exchange_strong_explicit Function.

atomic_compare_exchange_strong_explicit Function

Performs an atomic compare and exchange operation.

template <class T>
inline bool atomic_compare_exchange_strong_explicit(
    volatile atomic<Ty>* Atom, Ty* Exp, Ty Value,
    memory_order Order1,
    memory_order Order2) noexcept;

template <class Ty>
inline bool atomic_compare_exchange_strong_explicit(
    atomic<Ty>* Atom, Ty* Exp, Ty Value,
    memory_order Order1,
    memory_order Order2) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a value of type Ty.

Exp
A pointer to a value of type Ty.

Value
A value of type Ty.

Order1
First memory_order argument.

Order2
Second memory_order argument. The value of Order2 cannot be memory_order_release or memory_order_acq_rel, it cannot be stronger than the value of Order1.

Return Value

A bool that indicates the result of the value comparison.

Remarks

An atomic compare and exchange operation compares the value that is stored in the object that is pointed to by Atom against the value that is pointed to by Exp. If the values are equal, the the value that is stored in the object that is pointed to by atom is replaced with Val by using a read-modify-write operation and applying the memory order constraints that are specified by Order1. If the values are not equal, the operation replaces the value that is pointed to by Exp with the value that is stored in the object that is pointed to by Atom and applies the memory order constraints that are specified by Order2.

atomic_compare_exchange_weak Function

Performs a weak atomic compare and exchange operation.

template <class Ty>
inline bool atomic_compare_exchange_strong(
    volatile atomic<Ty>* Atom, Ty* Exp, Ty Value) noexcept;
template <class Ty>
inline bool atomic_compare_exchange_strong(
    atomic<Ty>* Atom, Ty* Exp, Ty Value) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a value of type Ty.

Exp
A pointer to a value of type Ty.

Value
A value of type Ty.

Return Value

A bool that indicates the result of the value comparison.

Remarks

This method performs a weak atomic compare and exchange operation that has implicit memory_order_seq_cstmemory_order arguments. For more information, see atomic_compare_exchange_weak_explicit Function.

atomic_compare_exchange_weak_explicit Function

Performs a weak atomic compare and exchange operation.

template <class Ty>
inline bool atomic_compare_exchange_weak_explicit(
    volatile atomic<Ty>* Atom, Ty* Exp, Ty Value,
    memory_order Order1,
    memory_order Order2) noexcept;
template <class Ty>
inline bool atomic_compare_exchange_weak_explicit(
    atomic<Ty>* Atom, Ty* Exp, Ty Value,
    memory_order Order1,
    memory_order Order2) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a value of type Ty.

Exp
A pointer to a value of type Ty.

Value
A value of type Ty.

Order1
First memory_order argument.

Order2
Second memory_order argument. The value of Order2 cannot be memory_order_release or memory_order_acq_rel, nor can it be stronger than the value of Order1.

Return Value

A bool that indicates the result of the value comparison.

Remarks

An atomic compare and exchange operation compares the value that is stored in the object that is pointed to by Atom with the value that is pointed to by Exp. If the values are equal, the operation replaces the value that is stored in the object that is pointed to by Atom with Val by using a read-modify-write operation and applying the memory-order constraints that are specified by Order1. If the values are not equal, the operation replaces the value that is pointed to by Exp with the value that is stored in the object that is pointed to by Atom and applies the memory-order constraints that are specified by Order2.

A weak atomic compare and exchange operation performs an exchange if the compared values are equal. However, if the values are not equal, the operation is not guaranteed to perform an exchange.

atomic_exchange Function

Uses Value to replace the stored value of Atom.

template <class T>
inline Ty atomic_exchange(
    volatile atomic<Ty>* _Atom, Ty Value) noexcept;
template <class Ty>
inline T atomic_exchange(
    atomic<Ty>* Atom, Ty Value) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a value of type Ty.

Value
A value of type Ty.

Return Value

The stored value of Atom before the exchange.

Remarks

The atomic_exchange function performs a read-modify-write operation to exchange the value that is stored in Atom with Value, using the memory_order_seq_cstmemory_order.

atomic_exchange_explicit Function

Replaces the stored value of Atom with Value.

template <class Ty>
inline Ty atomic_exchange_explicit(
    volatile atomic<Ty>* Atom, Ty Value,
    memory_order Order) noexcept;
template <class Ty>
inline Ty atomic_exchange_explicit(
    atomic<Ty>* Atom, Ty Value,
    memory_order Order) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a value of type Ty.

Value
A value of type Ty.

Order
A memory_order.

Return Value

The stored value of Atom before the exchange.

Remarks

The atomic_exchange_explicit function performs a read-modify-write operation to exchange the value that is stored in Atom with Value, within the memory constraints that are specified by Order.

atomic_fetch_add Function

Adds a value to an existing value that is stored in an atomic object.

template <class T>  
T* atomic_fetch_add(
    volatile atomic<T*>* Atom,
    ptrdiff_t Value) noexcept;

template <class T>  
T* atomic_fetch_add(
    atomic<T*>* Atom,
    ptrdiff_t Value) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a pointer to type T.

Value
A value of type ptrdiff_t.

Return Value

The value of the pointer contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_add function performs a read-modify-write operation to atomically add Value to the stored value in Atom, using the memory_order_seq_cstmemory_order constraint.

When the atomic type is atomic_address, Value has type ptrdiff_t and the operation treats the stored pointer as a char *.

This operation is also overloaded for integral types:

integral atomic_fetch_add(
    volatile atomic-integral* Atom,
    integral Value) noexcept;

integral atomic_fetch_add(
    atomic-integral* Atom,
    integral Value) noexcept;

atomic_fetch_add_explicit Function

Adds a value to an existing value that is stored in an atomic object.

template <class T>  
T* atomic_fetch_add_explicit(
    volatile atomic<T*>* Atom,
    ptrdiff_t Value,
    memory_order Order) noexcept;

template <class T>  
T* atomic_fetch_add_explicit(
    atomic<T*>* Atom,
    ptrdiff_t Value, memory_order Order) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a pointer to type T.

Value
A value of type ptrdiff_t.

Return Value

The value of the pointer contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_add_explicit function performs a read-modify-write operation to atomically add Value to the stored value in Atom, within the memory_order constraints that are specified by Order.

When the atomic type is atomic_address, Value has type ptrdiff_t and the operation treats the stored pointer as a char *.

This operation is also overloaded for integral types:

integral atomic_fetch_add_explicit(
    volatile atomic-integral* Atom,
    integral Value,
    memory_order Order) noexcept;

integral atomic_fetch_add_explicit(
    atomic-integral* Atom,
    integral Value,
    memory_order Order) noexcept;

atomic_fetch_and Function

Performs a bitwise and on a value and an existing value that is stored in an atomic object.

template <class T>
inline T atomic_fetch_and(
    volatile atomic<T>* Atom, T Value);

noexcept
template <class T>
inline T atomic_fetch_and(
    volatile atomic<T>* Atom, T Value);

noexcept

Parameters

Atom
A pointer to an atomic object that stores a value of type T.

Value
A value of type T.

Return Value

The value contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_and function performs a read-modify-write operation to replace the stored value of Atom with a bitwise and of Value and the current value that is stored in Atom, using the memory_order_seq_cstmemory_order constraint.

atomic_fetch_and_explicit Function

Performs a bitwise and of a value and an existing value that is stored in an atomic object.

template <class T>
inline T atomic_fetch_and_explicit(
    volatile atomic<T>* Atom, T Value,
    memory_order Order);

noexcepttemplate <class T>
inline T atomic_fetch_and_explicit(
    volatile atomic<T>* Atom, T Value,
    memory_order Order);

noexcept

Parameters

Atom
A pointer to an atomic object that stores a value of type T.

Value
A value of type T.

Order
A memory_order.

Return Value

The value contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_and_explicit function performs a read-modify-write operation to replace the stored value of Atom with a bitwise and of Value and the current value that is stored in Atom, within the memory constraints that are specified by Order.

atomic_fetch_or Function

Performs a bitwise or on a value and an existing value that is stored in an atomic object.

template <class T>
inline T atomic_fetch_or (
    volatile atomic<T>* Atom, T Value);

noexcept
template <class T>
inline T atomic_fetch_or (
    volatile atomic<T>* Atom, T Value);

noexcept

Parameters

Atom
A pointer to an atomic object that stores a value of type T.

Value
A value of type T.

Return Value

The value contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_or function performs a read-modify-write operation to replace the stored value of Atom with a bitwise or of Value and the current value that is stored in Atom, using the memory_order_seq_cstmemory_order.

atomic_fetch_or_explicit Function

Performs a bitwise or on a value and an existing value that is stored in an atomic object.

template <class T>
inline T atomic_fetch_or_explicit(
    volatile atomic<T>* Atom, T Value,
    memory_order Order);

noexcepttemplate <class T>
inline T atomic_fetch_or_explicit(
    volatile atomic<T>* Atom, T Value,
    memory_order Order);

noexcept

Parameters

Atom
A pointer to an atomic object that stores a value of type T.

Value
A value of type T.

Order
A memory_order.

Return Value

The value contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_or_explicit function performs a read-modify-write operation to replace the stored value of Atom with a bitwise or of Value and the current value that is stored in Atom, within the memory_order constraints specified by Order.

atomic_fetch_sub Function

Subtracts a value from an existing value that is stored in an atomic object.

template <class T>  
T* atomic_fetch_sub(
    volatile atomic<T*>* Atom,
    ptrdiff_t Value) noexcept;

template <class T>  
T* atomic_fetch_sub(
    atomic<T*>* Atom,
    ptrdiff_t Value) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a pointer to type T.

Value
A value of type ptrdiff_t.

Return Value

The value of the pointer contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_sub function performs a read-modify-write operation to atomically subtract Value from the stored value in Atom, using the memory_order_seq_cstmemory_order constraint.

When the atomic type is atomic_address, Value has type ptrdiff_t and the operation treats the stored pointer as a char *.

This operation is also overloaded for integral types:

integral atomic_fetch_sub(
    volatile atomic-integral* Atom,
    integral Value) noexcept;

integral atomic_fetch_sub(
    atomic-integral* Atom,
    integral Value) noexcept;

atomic_fetch_sub_explicit Function

Subtracts a value from an existing value that is stored in an atomic object.

template <class T>  
T* atomic_fetch_sub_explicit(
    volatile atomic<T*>* Atom,
    ptrdiff_t Value,
    memory_order Order) noexcept;

template <class T>  
T* atomic_fetch_sub_explicit(
    atomic<T*>* Atom,
    ptrdiff_t Value, memory_order Order) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a pointer to type T.

Value
A value of type ptrdiff_t.

Return Value

The value of the pointer contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_sub_explicit function performs a read-modify-write operation to atomically subtract Value from the stored value in Atom, within the memory_order constraints that are specified by Order.

When the atomic type is atomic_address, Value has type ptrdiff_t and the operation treats the stored pointer as a char *.

This operation is also overloaded for integral types:

integral atomic_fetch_sub_explicit(
    volatile atomic-integral* Atom,
    integral Value,
    memory_order Order) noexcept;

integral atomic_fetch_sub_explicit(
    atomic-integral* Atom,
    integral Value,
    memory_order Order) noexcept;

atomic_fetch_xor Function

Performs a bitwise exclusive or on a value and an existing value that is stored in an atomic object.

template <class T>
inline T atomic_fetch_xor(
    volatile atomic<T>* Atom, T Value);

noexcept

template <class T>
inline T atomic_fetch_xor(
    volatile atomic<T>* Atom, T Value);

noexcept

Parameters

Atom
A pointer to an atomic object that stores a value of type T.

Value
A value of type T.

Return Value

The value contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_xor function performs a read-modify-write operation to replace the stored value of Atom with a bitwise exclusive or of Value and the current value that is stored in Atom, using the memory_order_seq_cstmemory_order.

atomic_fetch_xor_explicit Function

Performs a bitwise exclusive or on a value and an existing value that is stored in an atomic object.

template <class T>
inline T atomic_fetch_xor_explicit(
    volatile atomic<T>* Atom, T Value,
    memory_order Order);

noexcepttemplate <class T>
inline T atomic_fetch_xor_explicit(
    volatile atomic<T>* Atom, T Value,
    memory_order Order);

noexcept

Parameters

Atom
A pointer to an atomic object that stores a value of type T.

Value
A value of type T.

Order
A memory_order.

Return Value

The value contained by the atomic object immediately before the operation was performed.

Remarks

The atomic_fetch_xor_explicit function performs a read-modify-write operation to replace the stored value of Atom with a bitwise exclusive or of Value and the current value that is stored in Atom, within the memory_order constraints that are specified by Order.

atomic_flag_clear Function

Sets the bool flag in an atomic_flag object to false, within the memory_order_seq_cstmemory_order.

inline void atomic_flag_clear(volatile atomic_flag* Flag) noexcept;
inline void atomic_flag_clear(atomic_flag* Flag) noexcept;

Parameters

Flag
A pointer to an atomic_flag object.

atomic_flag_clear_explicit Function

Sets the bool flag in an atomic_flag object to false, within the specified memory_order constraints.

inline void atomic_flag_clear_explicit(
    volatile atomic_flag* Flag,
    memory_order Order) noexcept;
inline void atomic_flag_clear_explicit(
    atomic_flag* Flag,
    memory_order Order) noexcept;

Parameters

Flag
A pointer to an atomic_flag object.

Order
A memory_order.

atomic_flag_test_and_set Function

Sets the bool flag in an atomic_flag object to true, within the constraints of the memory_order_seq_cstmemory_order.

inline bool atomic_flag_test_and_set(
    volatile atomic_flag* Flag,) noexcept;
inline bool atomic_flag_test_and_set(
    atomic_flag* Flag,) noexcept;

Parameters

Flag
A pointer to an atomic_flag object.

Return Value

The initial value of Flag.

atomic_flag_test_and_set_explicit Function

Sets the bool flag in an atomic_flag object to true, within the specified memory_order constraints.

inline bool atomic_flag_test_and_set_explicit(
    volatile atomic_flag* Flag,
    memory_order Order) noexcept;
inline bool atomic_flag_test_and_set_explicit(
    atomic_flag* Flag,
    memory_order Order) noexcept;

Parameters

Flag
A pointer to an atomic_flag object.

Order
A memory_order.

Return Value

The initial value of Flag.

atomic_init Function

Sets the stored value in an atomic object.

template <class Ty>
inline void atomic_init(
    volatile atomic<Ty>* Atom, Ty Value) noexcept;
template <class Ty>
inline void atomic_init(
    atomic<Ty>* Atom, Ty Value) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a value of type Ty.

Value
A value of type Ty.

Remarks

atomic_init is not an atomic operation. It is not thread-safe.

atomic_is_lock_free Function

Specifies whether atomic operations on an atomic object are lock-free.

template <class T>
inline bool atomic_is_lock_free(const volatile atomic<T>* Atom) noexcept;
template <class T>
inline bool atomic_is_lock_free(const atomic<T>* Atom) noexcept;

Parameters

Atom
A pointer to an atomic object that stores a value of type T.

Return Value

true if atomic operations on Atom are lock-free; otherwise, false.

Remarks

An atomic type is lock-free if no atomic operations on that type use locks. If this function returns true, the type is safe to use in signal-handlers.

atomic_load Function

Retrieves the stored value in an atomic object.

template <class Ty>
inline Ty atomic_load(const volatile atomic<Ty>* Atom) noexcept;
template <class Ty>
inline Ty atomic_load(const atomic<Ty>* Atom) noexcept;

Parameters

Atom
A pointer to an atomic object that contains a value of type Ty.

Return Value

The retrieved value that is stored in Atom.

Remarks

atomic_load implicitly uses the memory_order_seq_cstmemory_order.

atomic_load_explicit Function

Retrieves the stored value in an atomic object, within a specified memory_order.

template <class Ty>
inline Ty atomic_load_explicit(
    const volatile atomic<Ty>* Atom,
    memory_order Order) noexcept;
template <class Ty>
inline Ty atomic_load_explicit(
    const atomic<Ty>* Atom,
    memory_order Order) noexcept;

Parameters

Atom
A pointer to an atomic object that contains a value of type Ty.

Order
A memory_order. Do not use memory_order_release or memory_order_acq_rel.

Return Value

The retrieved value that is stored in Atom.

atomic_signal_fence Function

Acts as a fence—which is a memory synchronization primitive that enforces ordering between load/store operations—between other fences in a calling thread that have signal handlers that are executed in the same thread.

inline void atomic_signal_fence(memory_order Order) noexcept;

Parameters

Order
A memory ordering constraint that determines fence type.

Remarks

The Order argument determines fence type.

memory_order_relaxed The fence has no effect.
memory_order_consume The fence is an acquire fence.
memory_order_acquire The fence is an acquire fence.
memory_order_release The fence is a release fence.
memory_order_acq_rel The fence is both an acquire fence and a release fence.
memory_order_seq_cst The fence is both an acquire fence and a release fence, and is sequentially consistent.

atomic_store Function

Atomically stores a value in an atomic object.

template <class Ty>
inline Ty atomic_store_explicit(
    const volatile atomic<Ty>* Atom, Ty Value) noexcept;
template <class Ty>
inline Ty atomic_store_explicit(
    const atomic<Ty>* Atom, T Value) noexcept;

Parameters

Atom
A pointer to an atomic object that contains a value of type Ty.

Value
A value of type Ty.

Remarks

atomic_store stores Value in the object that is pointed to by Atom, within the memory_order_seq_cstmemory_order constraint.

atomic_store_explicit Function

Atomically stores a value in an atomic object.

template <class Ty>
inline Ty atomic_store_explicit(
    const volatile atomic<Ty>* Atom, Ty Value,
    memory_order Order) noexcept;
template <class Ty>
inline Ty atomic_store_explicit(
    const atomic<Ty>* Atom, T Value,
    memory_order Order) noexcept;

Parameters

Atom
A pointer to an atomic object that contains a value of type Ty.

Value
A value of type Ty.

Order
A memory_order. Do not use memory_order_consume, memory_order_acquire, or memory_order_acq_rel.

Remarks

atomic_store stores Value in the object that is pointed to by Atom, within the memory_order that is specified by Order.

atomic_thread_fence Function

Acts as a fence—which is a memory synchronization primitive that enforces ordering between load/store operations—without an associated atomic operation.

inline void atomic_thread_fence(memory_order Order) noexcept;

Parameters

Order
A memory ordering constraint that determines fence type.

Remarks

The Order argument determines fence type.

memory_order_relaxed The fence has no effect.
memory_order_consume The fence is an acquire fence.
memory_order_acquire The fence is an acquire fence.
memory_order_release The fence is a release fence.
memory_order_acq_rel The fence is both an acquire fence and a release fence.
memory_order_seq_cst The fence is both an acquire fence and a release fence, and is sequentially consistent.

kill_dependency Function

Removes a dependency.

template <class Ty>
Ty kill_dependency(Ty Arg) noexcept;

Parameters

Arg
A value of type Ty.

Return Value

The return value is Arg. The evaluation of Arg does not carry a dependency to the function call. By breaking a possible dependency chain, the function might permit the compiler to generate more efficient code.

See Also

<atomic>