31 Atomic operations library [atomics] (original) (raw)

31.10 Flag type and operations [atomics.flag]

namespace std { struct atomic_flag { constexpr atomic_flag() noexcept; atomic_flag(const atomic_flag&) = delete; atomic_flag& operator=(const atomic_flag&) = delete; atomic_flag& operator=(const atomic_flag&) volatile = delete;

bool test(memory_order = memory_order::seq_cst) const volatile noexcept;
bool test(memory_order = memory_order::seq_cst) const noexcept;
bool test_and_set(memory_order = memory_order::seq_cst) volatile noexcept;
bool test_and_set(memory_order = memory_order::seq_cst) noexcept;
void clear(memory_order = memory_order::seq_cst) volatile noexcept;
void clear(memory_order = memory_order::seq_cst) noexcept;

void wait(bool, memory_order = memory_order::seq_cst) const volatile noexcept;
void wait(bool, memory_order = memory_order::seq_cst) const noexcept;
void notify_one() volatile noexcept;
void notify_one() noexcept;
void notify_all() volatile noexcept;
void notify_all() noexcept;

}; }

The atomic_­flag type provides the classic test-and-set functionality.

It has two states, set and clear.

Operations on an object of type atomic_­flag shall be lock-free.

[ Note

:

Hence the operations should also be address-free.

— end note

]

The atomic_­flag type is a standard-layout struct.

It has a trivial destructor.

constexpr atomic_flag::atomic_flag() noexcept;

Effects:Initializes *this to the clear state.

bool atomic_flag_test(const volatile atomic_flag* object) noexcept;bool atomic_flag_test(const atomic_flag* object) noexcept;bool atomic_flag_test_explicit(const volatile atomic_flag* object, memory_order order) noexcept;bool atomic_flag_test_explicit(const atomic_flag* object, memory_order order) noexcept;bool atomic_flag::test(memory_order order = memory_order::seq_cst) const volatile noexcept;bool atomic_flag::test(memory_order order = memory_order::seq_cst) const noexcept;

For atomic_­flag_­test, let order be memory_­order​::​seq_­cst.

Preconditions: order is neither memory_­order​::​release nor memory_­order​::​acq_­rel.

Effects:Memory is affected according to the value of order.

Returns:Atomically returns the value pointed to by object or this.

bool atomic_flag_test_and_set(volatile atomic_flag* object) noexcept;bool atomic_flag_test_and_set(atomic_flag* object) noexcept;bool atomic_flag_test_and_set_explicit(volatile atomic_flag* object, memory_order order) noexcept;bool atomic_flag_test_and_set_explicit(atomic_flag* object, memory_order order) noexcept;bool atomic_flag::test_and_set(memory_order order = memory_order::seq_cst) volatile noexcept;bool atomic_flag::test_and_set(memory_order order = memory_order::seq_cst) noexcept;

Effects:Atomically sets the value pointed to by object or by this to true.

Memory is affected according to the value oforder.

These operations are atomic read-modify-write operations ([intro.multithread]).

Returns:Atomically, the value of the object immediately before the effects.

void atomic_flag_clear(volatile atomic_flag* object) noexcept;void atomic_flag_clear(atomic_flag* object) noexcept;void atomic_flag_clear_explicit(volatile atomic_flag* object, memory_order order) noexcept;void atomic_flag_clear_explicit(atomic_flag* object, memory_order order) noexcept;void atomic_flag::clear(memory_order order = memory_order::seq_cst) volatile noexcept;void atomic_flag::clear(memory_order order = memory_order::seq_cst) noexcept;

Preconditions:The order argument is neither memory_­order​::​consume,memory_­order​::​acquire, nor memory_­order​::​acq_­rel.

Effects:Atomically sets the value pointed to by object or by this tofalse.

Memory is affected according to the value of order.

void atomic_flag_wait(const volatile atomic_flag* object, bool old) noexcept;void atomic_flag_wait(const atomic_flag* object, bool old) noexcept;void atomic_flag_wait_explicit(const volatile atomic_flag* object,bool old, memory_order order) noexcept;void atomic_flag_wait_explicit(const atomic_flag* object,bool old, memory_order order) noexcept;void atomic_flag::wait(bool old, memory_order order = memory_order::seq_cst) const volatile noexcept;void atomic_flag::wait(bool old, memory_order order = memory_order::seq_cst) const noexcept;

For atomic_­flag_­wait, let order be memory_­order​::​seq_­cst.

Let flag be object for the non-member functions andthis for the member functions.

Preconditions: order is neither memory_­order​::​release nor memory_­order​::​acq_­rel.

Effects:Repeatedly performs the following steps, in order:

• Evaluates flag->test(order) != old.
• If the result of that evaluation is true, returns.
• Blocks until it is unblocked by an atomic notifying operation or is unblocked spuriously.

void atomic_flag_notify_one(volatile atomic_flag* object) noexcept;void atomic_flag_notify_one(atomic_flag* object) noexcept;void atomic_flag::notify_one() volatile noexcept;void atomic_flag::notify_one() noexcept;

Effects:Unblocks the execution of at least one atomic waiting operation that is eligible to be unblocked ([atomics.wait]) by this call, if any such atomic waiting operations exist.

Remarks:This function is an atomic notifying operation ([atomics.wait]).

void atomic_flag_notify_all(volatile atomic_flag* object) noexcept;void atomic_flag_notify_all(atomic_flag* object) noexcept;void atomic_flag::notify_all() volatile noexcept;void atomic_flag::notify_all() noexcept;

Effects:Unblocks the execution of all atomic waiting operations that are eligible to be unblocked ([atomics.wait]) by this call.

Remarks:This function is an atomic notifying operation ([atomics.wait]).