Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/atomic/atomic flag"

From cppreference.com
< cpp‎ | atomic
m (note on the lack of load/store)
m (rewrite example)
 
(35 intermediate revisions by 17 users not shown)
Line 1: Line 1:
{{cpp/title | atomic_flag}}
+
{{cpp/title|atomic_flag}}
 
{{cpp/atomic/atomic_flag/navbar}}
 
{{cpp/atomic/atomic_flag/navbar}}
{{ddcl list begin}}
+
{{dcl begin}}
{{ddcl list header | atomic}}
+
{{dcl header|atomic}}
{{ddcl list item | notes={{mark since c++11}} | 1=
+
{{dcl|since=c++11|1=
 
class atomic_flag;
 
class atomic_flag;
 
}}
 
}}
{{ddcl list end}}
+
{{dcl end}}
  
An {{c|std::atomic_flag}} is an atomic boolean type. Unlike all specializations of {{c|std::atomic}}, it is guaranteed to be lock-free. Unlike {{c|std::atomic<bool>}}, {{tt|std::atomic_flag}} does not provide load or store operations.
+
{{tt|std::atomic_flag}} is an atomic boolean type. Unlike all specializations of {{lc|std::atomic}}, it is guaranteed to be lock-free. Unlike {{c/core|std::atomic<bool>}}, {{tt|std::atomic_flag}} does not provide load or store operations.
  
 
===Member functions===
 
===Member functions===
{{dcl list begin}}
+
{{dsc begin}}
{{dcl list mem ctor | cpp/atomic/atomic_flag/atomic_flag   | constructs an atomic_flag }}
+
{{dsc mem ctor|cpp/atomic/atomic_flag/atomic_flag|constructs an atomic_flag}}
{{dcl list mem fun | cpp/atomic/atomic_flag/operator{{=}} | the assignment operator }}
+
{{dsc mem fun|cpp/atomic/atomic_flag/operator{{=}}|notes={{cmark deleted}}|the assignment operator (deleted)}}
{{dcl list template | cpp/atomic/atomic_flag/dcl list clear}}
+
{{dsc inc|cpp/atomic/atomic_flag/dsc clear}}
{{dcl list template | cpp/atomic/atomic_flag/dcl list test_and_set}}
+
{{dsc inc|cpp/atomic/atomic_flag/dsc test_and_set}}
{{dcl list end}}
+
{{dsc inc|cpp/atomic/atomic_flag/dsc test}}
 +
{{dsc inc|cpp/atomic/atomic/dsc wait|atomic_flag}}
 +
{{dsc inc|cpp/atomic/atomic/dsc notify_one|atomic_flag}}
 +
{{dsc inc|cpp/atomic/atomic/dsc notify_all|atomic_flag}}
 +
{{dsc end}}
  
 
===Example===
 
===Example===
 +
<!-- Note that https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering refers to here for spinlock -->
 
{{example
 
{{example
| A spinlock mutex can be implemented in userspace using an atomic_flag
+
|A [[enwiki:Spinlock|spinlock]] mutex demo can be implemented in userspace using an {{lc|atomic_flag}}. Do note that spinlock mutexes are [https://www.realworldtech.com/forum/?threadid{{=}}189711&curpostid{{=}}189723 extremely dubious] in practice.
| code=
+
|code=
 +
#include <atomic>
 +
#include <iostream>
 +
#include <mutex>
 
#include <thread>
 
#include <thread>
 
#include <vector>
 
#include <vector>
#include <iostream>
 
#include <atomic>
 
  
std::atomic_flag lock = ATOMIC_FLAG_INIT;
+
class mutex
 +
{
 +
    std::atomic_flag m_{};
 +
 
 +
  public:
 +
    void lock() noexcept
 +
    {
 +
        while (m_.test_and_set(std::memory_order_acquire))
 +
#if defined(__cpp_lib_atomic_wait) && __cpp_lib_atomic_wait >= 201907L
 +
            // Since C++20, locks can be acquired only after notification in the unlock,
 +
            // avoiding any unnecessary spinning.
 +
            // Note that even though wait gurantees it returns only after the value has
 +
            // changed, the lock is acquired after the next condition check.
 +
            m_.wait(true, std::memory_order_relaxed)
 +
#endif
 +
                ;
 +
    }
 +
    bool try_lock() noexcept
 +
    {
 +
        return !m_.test_and_set(std::memory_order_acquire);
 +
    }
 +
    void unlock() noexcept
 +
    {
 +
        m_.clear(std::memory_order_release);
 +
#if defined(__cpp_lib_atomic_wait) && __cpp_lib_atomic_wait >= 201907L
 +
        m_.notify_one();
 +
#endif
 +
    }
 +
};
 +
 
 +
static mutex m;
 +
 
 +
static int out{};
  
void f(int n)
+
void f(std::size_t n)
 
{
 
{
     for(int cnt = 0; cnt < 100; ++cnt) {
+
     for (std::size_t cnt{}; cnt < 40; ++cnt)
         while(lock.test_and_set(std::memory_order_acquire))  // acquire lock
+
    {
            ; // spin
+
         std::lock_guard lock{m};
         std::cout << "Output from thread " << n << '\n';
+
         std::cout << n << ((++out % 40) == 0 ? '\n' : ' ');
        lock.clear(std::memory_order_release);               // release lock
+
 
     }
 
     }
 
}
 
}
 +
 
int main()
 
int main()
 
{
 
{
 
     std::vector<std::thread> v;
 
     std::vector<std::thread> v;
     for (int n = 0; n < 10; ++n) {
+
     for (std::size_t n{}; n < 10; ++n)
 
         v.emplace_back(f, n);
 
         v.emplace_back(f, n);
    }
+
     for (auto &t : v)
     for (auto& t : v) {
+
 
         t.join();
 
         t.join();
    }
 
 
}
 
}
| output=
+
|p=true
Output from thread 2
+
|output=
Output from thread 6
+
0 1 1 2 0 1 3 2 3 2 0 1 2 3 2 3 0 1 3 2 0 1 2 3 2 3 0 3 2 3 2 3 2 3 1 2 3 0 1 3
Output from thread 7
+
2 3 2 0 1 2 3 0 1 2 3 2 0 1 2 3 0 1 2 3 2 3 2 3 2 0 1 2 3 2 3 0 1 3 2 3 0 2 1 1
...<exactly 1000 lines>...
+
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 3 2 0 2 3 2 3 2 3 2 3 2 3 0 3
 +
2 3 0 3 0 3 2 3 0 3 2 3 2 3 0 2 3 0 3 2 0 2 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
 +
4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4
 +
5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5
 +
6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6
 +
7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7
 +
8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8
 +
9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9
 
}}
 
}}
  
 
===See also===
 
===See also===
{{dcl list begin}}
+
{{dsc begin}}
{{dcl list template | cpp/atomic/dcl list atomic_flag_test_and_set}}
+
{{dsc inc|cpp/atomic/dsc atomic_flag_test_and_set}}
{{dcl list template | cpp/atomic/dcl list atomic_flag_clear}}
+
{{dsc inc|cpp/atomic/dsc atomic_flag_clear}}
{{dcl list template | cpp/atomic/dcl list ATOMIC_FLAG_INIT}}
+
{{dsc inc|cpp/atomic/dsc atomic_flag_wait}}
{{dcl list end}}
+
{{dsc inc|cpp/atomic/dsc atomic_flag_notify_one}}
 +
{{dsc inc|cpp/atomic/dsc atomic_flag_notify_all}}
 +
{{dsc inc|cpp/atomic/dsc ATOMIC_FLAG_INIT}}
 +
{{dsc see c|c/atomic/atomic_flag}}
 +
{{dsc end}}
 +
 
 +
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 01:04, 28 September 2024

 
 
Concurrency support library
Threads
(C++11)
(C++20)
this_thread namespace
(C++11)
(C++11)
(C++11)
Cooperative cancellation
Mutual exclusion
(C++11)
Generic lock management
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Condition variables
(C++11)
Semaphores
Latches and Barriers
(C++20)
(C++20)
Futures
(C++11)
(C++11)
(C++11)
(C++11)
Safe Reclamation
(C++26)
Hazard Pointers
Atomic types
(C++11)
(C++20)
atomic_flag
(C++11)
Initialization of atomic types
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
Memory ordering
Free functions for atomic operations
Free functions for atomic flags
 
 
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.

[edit] Member functions

constructs an atomic_flag
(public member function)
[deleted]
the assignment operator (deleted)
(public member function)
atomically sets flag to false
(public member function) [edit]
atomically sets the flag to true and obtains its previous value
(public member function) [edit]
(C++20)
atomically returns the value of the flag
(public member function) [edit]
(C++20)
blocks the thread until notified and the atomic value changes
(public member function) [edit]
notifies at least one thread waiting on the atomic object
(public member function) [edit]
notifies all threads blocked waiting on the atomic object
(public member function) [edit]

[edit] Example

A spinlock mutex demo can be implemented in userspace using an atomic_flag. Do note that spinlock mutexes are extremely dubious in practice.

#include <atomic>
#include <iostream>
#include <mutex>
#include <thread>
#include <vector>
 
class mutex
{
    std::atomic_flag m_{};
 
  public:
    void lock() noexcept
    {
        while (m_.test_and_set(std::memory_order_acquire))
#if defined(__cpp_lib_atomic_wait) && __cpp_lib_atomic_wait >= 201907L
            // Since C++20, locks can be acquired only after notification in the unlock,
            // avoiding any unnecessary spinning.
            // Note that even though wait gurantees it returns only after the value has
            // changed, the lock is acquired after the next condition check.
            m_.wait(true, std::memory_order_relaxed)
#endif
                ;
    }
    bool try_lock() noexcept
    {
        return !m_.test_and_set(std::memory_order_acquire);
    }
    void unlock() noexcept
    {
        m_.clear(std::memory_order_release);
#if defined(__cpp_lib_atomic_wait) && __cpp_lib_atomic_wait >= 201907L
        m_.notify_one();
#endif
    }
};
 
static mutex m;
 
static int out{};
 
void f(std::size_t n)
{
    for (std::size_t cnt{}; cnt < 40; ++cnt)
    {
        std::lock_guard lock{m};
        std::cout << n << ((++out % 40) == 0 ? '\n' : ' ');
    }
}
 
int main()
{
    std::vector<std::thread> v;
    for (std::size_t n{}; n < 10; ++n)
        v.emplace_back(f, n);
    for (auto &t : v)
        t.join();
}

Possible output:

0 1 1 2 0 1 3 2 3 2 0 1 2 3 2 3 0 1 3 2 0 1 2 3 2 3 0 3 2 3 2 3 2 3 1 2 3 0 1 3
2 3 2 0 1 2 3 0 1 2 3 2 0 1 2 3 0 1 2 3 2 3 2 3 2 0 1 2 3 2 3 0 1 3 2 3 0 2 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 3 2 0 2 3 2 3 2 3 2 3 2 3 0 3
2 3 0 3 0 3 2 3 0 3 2 3 2 3 0 2 3 0 3 2 0 2 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4
5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5
6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6
7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7
8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8
9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9

[edit] See also

atomically sets the flag to true and returns its previous value
(function) [edit]
atomically sets the value of the flag to false
(function) [edit]
blocks the thread until notified and the flag changes
(function) [edit]
notifies a thread blocked in atomic_flag_wait
(function) [edit]
notifies all threads blocked in atomic_flag_wait
(function) [edit]
initializes an std::atomic_flag to false
(macro constant) [edit]
C documentation for atomic_flag