StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Safe::Atomic< T > Class Template Reference

Atomic word of one, two, four or eight bytes. More...

#include <StormByte/safe/atomic.hxx>

Public Member Functions

 Atomic ()
 Zero-initialized value.
 Atomic (T desired)
 Value-initialized word.
 Atomic (const Atomic &)=delete
 Atomic (Atomic &&)=delete
 ~Atomic () noexcept
 Destroys the word on Base's heap.
Atomic & operator= (const Atomic &)=delete
Atomic & operator= (Atomic &&)=delete
T operator= (T desired) noexcept
 Store a value.
bool is_lock_free () const noexcept
 Whether Base's word is lock-free.
T load (MemoryOrder order=MemoryOrder::SeqCst) const noexcept
 Load the value.
void store (T desired, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Store a value.
T exchange (T desired, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Replace the value.
bool compare_exchange_weak (T &expected, T desired, MemoryOrder success, MemoryOrder failure) noexcept
 Weak compare-exchange.
bool compare_exchange_weak (T &expected, T desired, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Weak compare-exchange with one order.
bool compare_exchange_strong (T &expected, T desired, MemoryOrder success, MemoryOrder failure) noexcept
 Strong compare-exchange.
bool compare_exchange_strong (T &expected, T desired, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Strong compare-exchange with one order.
void wait (T old, MemoryOrder order=MemoryOrder::SeqCst) const noexcept
 Wait while the value is still old.
void notify_one () noexcept
 Wake one waiter.
void notify_all () noexcept
 Wake every waiter.
template<class Delta>
requires ((Type::Integral<T> && std::is_same_v<Delta, T>) || (Type::Pointer<T> && sizeof(std::remove_pointer_t<T>) > 0 && std::is_integral_v<Delta> && std::is_convertible_v<Delta, std::ptrdiff_t>))
T fetch_add (Delta delta, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Add and return the previous value.
template<class Delta>
requires ((Type::Integral<T> && std::is_same_v<Delta, T>) || (Type::Pointer<T> && sizeof(std::remove_pointer_t<T>) > 0 && std::is_integral_v<Delta> && std::is_convertible_v<Delta, std::ptrdiff_t>))
T fetch_sub (Delta delta, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Subtract and return the previous value.
T fetch_and (T bits, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Bitwise and, returning the previous value.
T fetch_or (T bits, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Bitwise or, returning the previous value.
T fetch_xor (T bits, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Bitwise xor, returning the previous value.
T fetch_max (T value, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Replace the value with the greater of it and value.
T fetch_min (T value, MemoryOrder order=MemoryOrder::SeqCst) noexcept
 Replace the value with the lesser of it and value.
T operator++ () noexcept
 Pre-increment.
T operator++ (int) noexcept
 Post-increment.
T operator-- () noexcept
 Pre-decrement.
T operator-- (int) noexcept
 Post-decrement.
T operator+= (T delta) noexcept
 Add and return the new value.
T operator-= (T delta) noexcept
 Subtract and return the new value.
T operator&= (T bits) noexcept
 And and return the new value.
T operator|= (T bits) noexcept
 Or and return the new value.
T operator^= (T bits) noexcept
 Xor and return the new value.
 operator T () const noexcept
 Sequentially consistent load.

Detailed Description

template<class T>
class StormByte::Safe::Atomic< T >

Atomic word of one, two, four or eight bytes.

Not an alias of std::atomic. The template copies bytes in the caller. The word lives on Base's heap.

Template Parameters
TTrivially copyable integer, bool, enum or object pointer.

Constructor & Destructor Documentation

◆ Atomic() [1/4]

template<class T>
StormByte::Safe::Atomic< T >::Atomic ( )
inline

Zero-initialized value.

Exceptions
AllocationErrorThe word cannot be allocated.

◆ Atomic() [2/4]

template<class T>
StormByte::Safe::Atomic< T >::Atomic ( T desired)
inlineexplicit

Value-initialized word.

Parameters
desiredInitial value.
Exceptions
AllocationErrorThe word cannot be allocated.

◆ Atomic() [3/4]

template<class T>
StormByte::Safe::Atomic< T >::Atomic ( const Atomic< T > & )
delete

◆ Atomic() [4/4]

template<class T>
StormByte::Safe::Atomic< T >::Atomic ( Atomic< T > && )
delete

◆ ~Atomic()

template<class T>
StormByte::Safe::Atomic< T >::~Atomic ( )
inlinenoexcept

Destroys the word on Base's heap.

Member Function Documentation

◆ compare_exchange_strong() [1/2]

template<class T>
bool StormByte::Safe::Atomic< T >::compare_exchange_strong ( T & expected,
T desired,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Strong compare-exchange with one order.

Parameters
expectedExpected value.
desiredValue to store on success.
orderSuccess order.
Returns
Whether the exchange happened.

◆ compare_exchange_strong() [2/2]

template<class T>
bool StormByte::Safe::Atomic< T >::compare_exchange_strong ( T & expected,
T desired,
MemoryOrder success,
MemoryOrder failure )
inlinenoexcept

Strong compare-exchange.

Parameters
expectedExpected value. Replaced with the actual value on failure.
desiredValue to store on success.
successOrder on success.
failureOrder on failure. Release and acq-rel are promoted to acquire.
Returns
Whether the exchange happened.

◆ compare_exchange_weak() [1/2]

template<class T>
bool StormByte::Safe::Atomic< T >::compare_exchange_weak ( T & expected,
T desired,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Weak compare-exchange with one order.

Parameters
expectedExpected value.
desiredValue to store on success.
orderSuccess order. Failure is the matching acquire or relaxed order.
Returns
Whether the exchange happened.

◆ compare_exchange_weak() [2/2]

template<class T>
bool StormByte::Safe::Atomic< T >::compare_exchange_weak ( T & expected,
T desired,
MemoryOrder success,
MemoryOrder failure )
inlinenoexcept

Weak compare-exchange.

Parameters
expectedExpected value. Replaced with the actual value on failure.
desiredValue to store on success.
successOrder on success.
failureOrder on failure. Release and acq-rel are promoted to acquire.
Returns
Whether the exchange happened.

◆ exchange()

template<class T>
T StormByte::Safe::Atomic< T >::exchange ( T desired,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Replace the value.

Parameters
desiredNew value.
orderOrder.
Returns
Previous value.

◆ fetch_add()

template<class T>
template<class Delta>
requires ((Type::Integral<T> && std::is_same_v<Delta, T>) || (Type::Pointer<T> && sizeof(std::remove_pointer_t<T>) > 0 && std::is_integral_v<Delta> && std::is_convertible_v<Delta, std::ptrdiff_t>))
T StormByte::Safe::Atomic< T >::fetch_add ( Delta delta,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Add and return the previous value.

Template Parameters
DeltaT for an integer. An integer convertible to std::ptrdiff_t for an object pointer, counted in elements.
Parameters
deltaAddend.
orderOrder.
Returns
Previous value.

A member template so an explicit class instantiation does not emit it. On Windows ptrdiff_t is long long, and MSVC does not mangle a requires clause. An integer literal is int, not ptrdiff_t, so the pointer path accepts the conversion.

◆ fetch_and()

template<class T>
T StormByte::Safe::Atomic< T >::fetch_and ( T bits,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Bitwise and, returning the previous value.

Parameters
bitsMask.
orderOrder.
Returns
Previous value.

◆ fetch_max()

template<class T>
T StormByte::Safe::Atomic< T >::fetch_max ( T value,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Replace the value with the greater of it and value.

Parameters
valueCandidate.
orderOrder.
Returns
Previous value.

One function for an integer and an object pointer. MSVC does not mangle a requires clause, so a second overload with the same signature is a redefinition.

◆ fetch_min()

template<class T>
T StormByte::Safe::Atomic< T >::fetch_min ( T value,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Replace the value with the lesser of it and value.

Parameters
valueCandidate.
orderOrder.
Returns
Previous value.

◆ fetch_or()

template<class T>
T StormByte::Safe::Atomic< T >::fetch_or ( T bits,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Bitwise or, returning the previous value.

Parameters
bitsMask.
orderOrder.
Returns
Previous value.

◆ fetch_sub()

template<class T>
template<class Delta>
requires ((Type::Integral<T> && std::is_same_v<Delta, T>) || (Type::Pointer<T> && sizeof(std::remove_pointer_t<T>) > 0 && std::is_integral_v<Delta> && std::is_convertible_v<Delta, std::ptrdiff_t>))
T StormByte::Safe::Atomic< T >::fetch_sub ( Delta delta,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Subtract and return the previous value.

Template Parameters
DeltaT for an integer. An integer convertible to std::ptrdiff_t for an object pointer, counted in elements.
Parameters
deltaSubtrahend.
orderOrder.
Returns
Previous value.

◆ fetch_xor()

template<class T>
T StormByte::Safe::Atomic< T >::fetch_xor ( T bits,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Bitwise xor, returning the previous value.

Parameters
bitsMask.
orderOrder.
Returns
Previous value.

◆ is_lock_free()

template<class T>
bool StormByte::Safe::Atomic< T >::is_lock_free ( ) const
inlinenoexcept

Whether Base's word is lock-free.

Returns
Lock-free flag of the Base word.

◆ load()

template<class T>
T StormByte::Safe::Atomic< T >::load ( MemoryOrder order = MemoryOrder::SeqCst) const
inlinenoexcept

Load the value.

Parameters
orderLoad order.
Returns
Current value.

◆ notify_all()

template<class T>
void StormByte::Safe::Atomic< T >::notify_all ( )
inlinenoexcept

Wake every waiter.

◆ notify_one()

template<class T>
void StormByte::Safe::Atomic< T >::notify_one ( )
inlinenoexcept

Wake one waiter.

◆ operator T()

template<class T>
StormByte::Safe::Atomic< T >::operator T ( ) const
inlinenoexcept

Sequentially consistent load.

Returns
Current value.

◆ operator&=()

template<class T>
T StormByte::Safe::Atomic< T >::operator&= ( T bits)
inlinenoexcept

And and return the new value.

Parameters
bitsMask.
Returns
New value.

◆ operator++() [1/2]

template<class T>
T StormByte::Safe::Atomic< T >::operator++ ( )
inlinenoexcept

Pre-increment.

Returns
New value.

◆ operator++() [2/2]

template<class T>
T StormByte::Safe::Atomic< T >::operator++ ( int )
inlinenoexcept

Post-increment.

Returns
Previous value.

◆ operator+=()

template<class T>
T StormByte::Safe::Atomic< T >::operator+= ( T delta)
inlinenoexcept

Add and return the new value.

Parameters
deltaAddend.
Returns
New value.

◆ operator--() [1/2]

template<class T>
T StormByte::Safe::Atomic< T >::operator-- ( )
inlinenoexcept

Pre-decrement.

Returns
New value.

◆ operator--() [2/2]

template<class T>
T StormByte::Safe::Atomic< T >::operator-- ( int )
inlinenoexcept

Post-decrement.

Returns
Previous value.

◆ operator-=()

template<class T>
T StormByte::Safe::Atomic< T >::operator-= ( T delta)
inlinenoexcept

Subtract and return the new value.

Parameters
deltaSubtrahend.
Returns
New value.

◆ operator=() [1/3]

template<class T>
Atomic & StormByte::Safe::Atomic< T >::operator= ( Atomic< T > && )
delete

◆ operator=() [2/3]

template<class T>
Atomic & StormByte::Safe::Atomic< T >::operator= ( const Atomic< T > & )
delete

◆ operator=() [3/3]

template<class T>
T StormByte::Safe::Atomic< T >::operator= ( T desired)
inlinenoexcept

Store a value.

Parameters
desiredNew value.
Returns
The stored value.

◆ operator^=()

template<class T>
T StormByte::Safe::Atomic< T >::operator^= ( T bits)
inlinenoexcept

Xor and return the new value.

Parameters
bitsMask.
Returns
New value.

◆ operator|=()

template<class T>
T StormByte::Safe::Atomic< T >::operator|= ( T bits)
inlinenoexcept

Or and return the new value.

Parameters
bitsMask.
Returns
New value.

◆ store()

template<class T>
void StormByte::Safe::Atomic< T >::store ( T desired,
MemoryOrder order = MemoryOrder::SeqCst )
inlinenoexcept

Store a value.

Parameters
desiredNew value.
orderStore order.

◆ wait()

template<class T>
void StormByte::Safe::Atomic< T >::wait ( T old,
MemoryOrder order = MemoryOrder::SeqCst ) const
inlinenoexcept

Wait while the value is still old.

Parameters
oldCaptured value.
orderLoad order used by the wait.

The documentation for this class was generated from the following file: