etl/docs/utilities/atomic.md

title
atomic

{{< callout type="info">}} Header: atomic.h
Since: 11.0.0
Similar to: atomic {{< /callout >}}

This header attempts to replicate some of the types from std::atomic.

If ETL_USING_CPP11 and ETL_USING_STL are defined as 1 then etl::atomic will be defined in terms of std::atomic.
Otherwise it will be implemented in terms of the built-in support, if available, from the compiler. For example, early GCC and Arm compilers will use the __sync built-ins, later versions use __atomic built-ins.

If a type cannot be handled by the built-ins then the types are wrapped by etl::mutex.

If there is an ETL atomic type available for your platform then ETL_HAS_ATOMIC will be set to 1, otherwise it will be set to 0.

From: 20.40.0 etl::atomic supports the is_always_lock_free property.

For GCC and clang built-ins:
Integrals and pointers are lock free.
All other types are not lock free.

---

template <typename T>
struct atomic;

template <typename T>
struct atomic<T*>;

Memory order

memory_order_relaxed  
memory_order_consume  
memory_order_acquire  
memory_order_release  
memory_order_acq_rel  
memory_order_seq_cst  

Constructors

ETL_CONSTEXPR atomic()

Description
Value initialises T.

---

ETL_CONSTEXPR atomic(T v)

Description
Initialises T with v.

Assignment

T operator=(T v)
T operator=(T v) volatile

Description
Stores the value 'v'.

Increment

 T operator++()
 T operator++() volatile

Description
Pre-increments the atomic value by one.

---

 T operator++(int)
 T operator++(int) volatile

Description
Post-increments the atomic value by one.

Decrement

T operator--()
T operator--() volatile

Description
Pre-decrements the atomic value by one.

---

T operator--(int)
T operator--(int) volatile

Description
Post-decrements the atomic value by one.

Add

T operator+=(T v)
T operator+=(T v) volatile

Description
Adds to the atomic value.

Subtract

T operator-=(T v)
T operator-=(T v) volatile

Description
Subtracts from the atomic value.

And

T operator&=(T v)
T operator&=(T v) volatile

Description
Performs bitwise AND with the atomic value.

Or

T operator|=(T v)
T operator|=(T v) volatile

Description
Performs bitwise OR with the atomic value.

Exclusive or

T operator^=(T v)
T operator^=(T v) volatile

Description
Performs bitwise XOR with the atomic value.

Conversion operator

operator T() const
operator T() volatile const

Description
Loads a value from an atomic object.

Is lock free

bool is_lock_free() const
bool is_lock_free() const volatile

Description
Checks if the atomic object is lock-free.

Store

void store(T v, etl::memory_order order = etl::memory_order_seq_cst)
void store(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically replaces the value of the atomic object with a non-atomic argument.

Load

T load(etl::memory_order order = etl::memory_order_seq_cst) const
T load(etl::memory_order order = etl::memory_order_seq_cst) const volatile

Description
Atomically obtains the value of the atomic object.

Fetch add

T fetch_add(T v, etl::memory_order order = etl::memory_order_seq_cst)
T fetch_add(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically adds the argument to the value stored in the atomic object and obtains the value held previously.

Fetch subtract

T fetch_sub(T v, etl::memory_order order = etl::memory_order_seq_cst)
T fetch_sub(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically subtracts the argument to the value stored in the atomic object and obtains the value held previously.

Fetch or

T fetch_or(T v, etl::memory_order order = etl::memory_order_seq_cst)
T fetch_or(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically performs bitwise OR between the argument and the value of the atomic object and obtains the value held previously.

Fetch and

T fetch_and(T v, etl::memory_order order = etl::memory_order_seq_cst)
T fetch_and(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically performs bitwise AND between the argument and the value of the atomic object and obtains the value held previously.

Fetch exclusive or

T fetch_xor(T v, etl::memory_order order = etl::memory_order_seq_cst)
T fetch_xor(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically performs bitwise XOR between the argument and the value of the atomic object and obtains the value held previously.

Fetch max

T fetch_max(T v, etl::memory_order order = etl::memory_order_seq_cst)
T fetch_max(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically performs max between the argument and the value of the atomic object and obtains the value held previously.

Fetch min

T fetch_min(T v, etl::memory_order order = etl::memory_order_seq_cst)
T fetch_min(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically performs min between the argument and the value of the atomic object and obtains the value held previously.

Exchange

T exchange(T v, etl::memory_order order = etl::memory_order_seq_cst)
T exchange(T v, etl::memory_order order = etl::memory_order_seq_cst) volatile

Description
Atomically replaces the value of the atomic object and obtains the value held previously.

Compare exchange weak

bool compare_exchange_weak(T& expected, T desired, etl::memory_order order = etl::memory_order_seq_cst)
bool compare_exchange_weak(T& expected, T desired, etl::memory_order order = etl::memory_order_seq_cst) volatile
bool compare_exchange_weak(T& expected, T desired, etl::memory_order success, etl::memory_order failure)
bool compare_exchange_weak(T& expected, T desired, etl::memory_order success, etl::memory_order failure) volatile

Description
Atomically compares the value of the atomic object with non-atomic argument and performs atomic exchange if equal or atomic load if not.

Compare exchange strong

bool compare_exchange_strong(T& expected, T desired, etl::memory_order order = etl::memory_order_seq_cst)
bool compare_exchange_strong(T& expected, T desired, etl::memory_order order = etl::memory_order_seq_cst) volatile
bool compare_exchange_strong(T& expected, T desired, etl::memory_order success, etl::memory_order failure)
bool compare_exchange_strong(T& expected, T desired, etl::memory_order success, etl::memory_order failure) volatile

Description
Atomically compares the value of the atomic object with non-atomic argument and performs atomic exchange if equal or atomic load if not.