std::atomic_flag

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Atomic operations library

Types

atomic (C++11)

atomic_ref (C++20)

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_is_lock_free (C++11)

atomic_waitatomic_wait_explicit (C++20)(C++20)

atomic_notify_one (C++20)

atomic_notify_all (C++20)

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)

atomic_flag_testatomic_flag_test_explicit (C++20)(C++20)

atomic_flag_waitatomic_flag_wait_explicit (C++20)(C++20)

atomic_flag_notify_one (C++20)

atomic_flag_notify_all (C++20)

Initialization

atomic_init (C++11)(deprecated in C++20)

ATOMIC_VAR_INIT (C++11)(deprecated in C++20)

ATOMIC_FLAG_INIT (C++11)(deprecated in C++20)

Memory ordering

memory_order (C++11)

kill_dependency (C++11)

atomic_thread_fence (C++11)

atomic_signal_fence (C++11)

 

std::atomic_flag

Member functions

atomic_flag::atomic_flag

atomic_flag::operator=

atomic_flag::clear

atomic_flag::test_and_set

atomic_flag::test (C++20)

atomic_flag::wait (C++20)

atomic_flag::notify_one (C++20)

atomic_flag::notify_all (C++20)

 

Defined in header <atomic>
class atomic_flag;		(since C++11)

std::atomic_flag is an atomic boolean type. Unlike all specializations of std::atomic, it is guaranteed to be lock-free. Unlike std::atomic<bool>, std::atomic_flag does not provide load or store operations.

Member functions

(constructor)	constructs an atomic_flag (public member function)
operator=	the assignment operator (public member function)
clear	atomically sets flag to false (public member function)
test_and_set	atomically sets the flag to true and obtains its previous value (public member function)
test (C++20)	atomically returns the value of the flag (public member function)
wait (C++20)	blocks the thread until notified and the atomic value changes (public member function)
notify_one (C++20)	notifies at least one thread waiting on the atomic object (public member function)
notify_all (C++20)	notifies all threads blocked waiting on the atomic object (public member function)

Example

A spinlock mutex can be implemented in userspace using an atomic_flag

Run this code

#include <thread>
#include <vector>
#include <iostream>
#include <atomic>
 
std::atomic_flag lock = ATOMIC_FLAG_INIT;
 
void f(int n)
{
    for (int cnt = 0; cnt < 100; ++cnt) {
        while (lock.test_and_set(std::memory_order_acquire))  // acquire lock
             ; // spin
        std::cout << "Output from thread " << n << '\n';
        lock.clear(std::memory_order_release);               // release lock
    }
}
 
int main()
{
    std::vector<std::thread> v;
    for (int n = 0; n < 10; ++n) {
        v.emplace_back(f, n);
    }
    for (auto& t : v) {
        t.join();
    }
}

Output:

Output from thread 2
Output from thread 6
Output from thread 7
...<exactly 1000 lines>...

Starting in C++20, it can be optimized to write atomic_flag value only when there's a chance to acquire lock

Run this code

#include <thread>
#include <vector>
#include <iostream>
#include <atomic>
 
std::atomic_flag lock = ATOMIC_FLAG_INIT;
 
void f(int n)
{
    for (int cnt = 0; cnt < 100; ++cnt) {
        while (lock.test_and_set(std::memory_order_acquire))  // acquire lock
             while (lock.test(std::memory_order_relaxed))     // test lock
                 ; // spin
        std::cout << "Output from thread " << n << '\n';
        lock.clear(std::memory_order_release);                // release lock
    }
}
 
int main()
{
    std::vector<std::thread> v;
    for (int n = 0; n < 10; ++n) {
        v.emplace_back(f, n);
    }
    for (auto& t : v) {
        t.join();
    }
}

Output:

Output from thread 2
Output from thread 6
Output from thread 7
...<exactly 1000 lines>...

See also

atomic_flag_test_and_setatomic_flag_test_and_set_explicit (C++11)(C++11)	atomically sets the flag to true and returns its previous value (function)
atomic_flag_clearatomic_flag_clear_explicit (C++11)(C++11)	atomically sets the value of the flag to false (function)
atomic_flag_waitatomic_flag_wait_explicit (C++20)(C++20)	blocks the thread until notified and the flag changes (function)
atomic_flag_notify_one (C++20)	notifies a thread blocked in atomic_flag_wait (function)
atomic_flag_notify_all (C++20)	notifies all threads blocked in atomic_flag_wait (function)
ATOMIC_FLAG_INIT (C++11)(deprecated in C++20)	initializes an std::atomic_flag to false (macro constant)