QAtomicInteger Class

template <typename T> class QAtomicInteger

The QAtomicInteger class provides platform-independent atomic operations on integers. More...

Header: #include <QAtomicInteger>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Inherited By:

QAtomicInt

Public Functions

QAtomicInteger(T value = 0)
QAtomicInteger(const QAtomicInteger<T> &other)
bool deref()
T fetchAndAddAcquire(T valueToAdd)
T fetchAndAddOrdered(T valueToAdd)
T fetchAndAddRelaxed(T valueToAdd)
T fetchAndAddRelease(T valueToAdd)
T fetchAndAndAcquire(T valueToAnd)
T fetchAndAndOrdered(T valueToAnd)
T fetchAndAndRelaxed(T valueToAnd)
T fetchAndAndRelease(T valueToAnd)
T fetchAndOrAcquire(T valueToOr)
T fetchAndOrOrdered(T valueToOr)
T fetchAndOrRelaxed(T valueToOr)
T fetchAndOrRelease(T valueToOr)
T fetchAndStoreAcquire(T newValue)
T fetchAndStoreOrdered(T newValue)
T fetchAndStoreRelaxed(T newValue)
T fetchAndStoreRelease(T newValue)
T fetchAndSubAcquire(T valueToSub)
T fetchAndSubOrdered(T valueToSub)
T fetchAndSubRelaxed(T valueToSub)
T fetchAndSubRelease(T valueToSub)
T fetchAndXorAcquire(T valueToXor)
T fetchAndXorOrdered(T valueToXor)
T fetchAndXorRelaxed(T valueToXor)
T fetchAndXorRelease(T valueToXor)
T loadAcquire() const
T loadRelaxed() const
bool ref()
void storeRelaxed(T newValue)
void storeRelease(T newValue)
bool testAndSetAcquire(T expectedValue, T newValue)
bool testAndSetAcquire(T expectedValue, T newValue, T &currentValue)
bool testAndSetOrdered(T expectedValue, T newValue)
bool testAndSetOrdered(T expectedValue, T newValue, T &currentValue)
bool testAndSetRelaxed(T expectedValue, T newValue)
bool testAndSetRelaxed(T expectedValue, T newValue, T &currentValue)
bool testAndSetRelease(T expectedValue, T newValue)
bool testAndSetRelease(T expectedValue, T newValue, T &currentValue)
T operator T() const
T operator&=(T value)
T operator++()
T operator++(int)
T operator+=(T value)
T operator--()
T operator--(int)
T operator-=(T value)
QAtomicInteger<T> &operator=(T)
QAtomicInteger<T> &operator=(const QAtomicInteger<T> &other)
T operator^=(T value)
T operator|=(T value)

Static Public Members

(since 6.7) void qYieldCpu()

Macros

Detailed Description

For atomic operations on pointers, see the QAtomicPointer class.

An atomic operation is a complex operation that completes without interruption. The QAtomicInteger class provides atomic reference counting, test-and-set, fetch-and-store, and fetch-and-add for integers.

The template parameter T must be a C++ integer type:

  • 8-bit: bool, char, signed char, unsigned char, qint8, quint8, char8_t (C++20)
  • 16-bit: short, unsigned short, qint16, quint16, char16_t
  • 32-bit: int, unsigned int, qint32, quint32, char32_t
  • 64-bit: long long, unsigned long long, qint64, quint64
  • platform-specific size: long, unsigned long
  • pointer size: qintptr, quintptr, qptrdiff

Of the list above, only the 8-bit, 16-bit, 32-bit- and pointer-sized instantiations are guaranteed to work on all platforms. Support for other sizes depends on the compiler and processor architecture the code is being compiled for. To test whether the 64-bit types are supported on 32-bit platforms, check the macro Q_ATOMIC_INT64_IS_SUPPORTED.

The Atomic API

Reference counting

The ref() and deref() functions provide an efficient reference counting API. The return value of these functions are used to indicate when the last reference has been released. These functions allow you to implement your own implicitly shared classes.

MySharedType &MySharedType::operator=(const MySharedType &other)
{
    (void) other.data->atomicInt.ref();
    if (!data->atomicInt.deref()) {
        // The last reference has been released
        delete d;
    }
    d = other.d;
    return *this;
}

Memory ordering

QAtomicInteger provides several implementations of the atomic test-and-set, fetch-and-store, and fetch-and-add functions. Each implementation defines a memory ordering semantic that describes how memory accesses surrounding the atomic instruction are executed by the processor. Since many modern architectures allow out-of-order execution and memory ordering, using the correct semantic is necessary to ensure that your application functions properly on all processors.

  • Relaxed - memory ordering is unspecified, leaving the compiler and processor to freely reorder memory accesses.
  • Acquire - memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.
  • Release - memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.
  • Ordered - the same Acquire and Release semantics combined.

Test-and-set

If the current value of the QAtomicInteger is an expected value, the test-and-set functions assign a new value to the QAtomicInteger and return true. If values are not the same, these functions do nothing and return false. This operation equates to the following code:

if (currentValue == expectedValue) {
    currentValue = newValue;
    return true;
}
return false;

There are 4 test-and-set functions: testAndSetRelaxed(), testAndSetAcquire(), testAndSetRelease(), and testAndSetOrdered(). See above for an explanation of the different memory ordering semantics.

Fetch-and-store

The atomic fetch-and-store functions read the current value of the QAtomicInteger and then assign a new value, returning the original value. This operation equates to the following code:

int originalValue = currentValue;
currentValue = newValue;
return originalValue;

There are 4 fetch-and-store functions: fetchAndStoreRelaxed(), fetchAndStoreAcquire(), fetchAndStoreRelease(), and fetchAndStoreOrdered(). See above for an explanation of the different memory ordering semantics.

Fetch-and-add

The atomic fetch-and-add functions read the current value of the QAtomicInteger and then add the given value to the current value, returning the original value. This operation equates to the following code:

int originalValue = currentValue;
currentValue += valueToAdd;
return originalValue;

There are 4 fetch-and-add functions: fetchAndAddRelaxed(), fetchAndAddAcquire(), fetchAndAddRelease(), and fetchAndAddOrdered(). See above for an explanation of the different memory ordering semantics.

Feature Tests for the Atomic API

Providing a platform-independent atomic API that works on all processors is challenging. The API provided by QAtomicInteger is guaranteed to work atomically on all processors. However, since not all processors implement support for every operation provided by QAtomicInteger, it is necessary to expose information about the processor.

You can check at compile time which features are supported on your hardware using various macros. These will tell you if your hardware always, sometimes, or does not support a particular operation. The macros have the form Q_ATOMIC_INTnn_OPERATION_IS_HOW_NATIVE. nn is the size of the integer (in bits), OPERATION is one of REFERENCE_COUNTING, TEST_AND_SET, FETCH_AND_STORE, or FETCH_AND_ADD, and HOW is one of ALWAYS, SOMETIMES, or NOT. There will always be exactly one defined macro per operation. For example, if Q_ATOMIC_INT32_REFERENCE_COUNTING_IS_ALWAYS_NATIVE is defined, neither Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE nor Q_ATOMIC_INT32_REFERENCE_COUNTING_IS_NOT_NATIVE will be defined.

An operation that completes in constant time is said to be wait-free. Such operations are not implemented using locks or loops of any kind. For atomic operations that are always supported, and that are wait-free, Qt defines the Q_ATOMIC_INTnn_OPERATION_IS_WAIT_FREE in addition to the Q_ATOMIC_INTnn_OPERATION_IS_ALWAYS_NATIVE.

In cases where an atomic operation is only supported in newer generations of the processor, QAtomicInteger also provides a way to check at runtime what your hardware supports with the isReferenceCountingNative(), isTestAndSetNative(), isFetchAndStoreNative(), and isFetchAndAddNative() functions. Wait-free implementations can be detected using the isReferenceCountingWaitFree(), isTestAndSetWaitFree(), isFetchAndStoreWaitFree(), and isFetchAndAddWaitFree() functions.

Below is a complete list of all feature macros for QAtomicInteger:

  • Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_ALWAYS_NATIVE
  • Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE
  • Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_NOT_NATIVE
  • Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_WAIT_FREE
  • Q_ATOMIC_INTnn_TEST_AND_SET_IS_ALWAYS_NATIVE
  • Q_ATOMIC_INTnn_TEST_AND_SET_IS_SOMETIMES_NATIVE
  • Q_ATOMIC_INTnn_TEST_AND_SET_IS_NOT_NATIVE
  • Q_ATOMIC_INTnn_TEST_AND_SET_IS_WAIT_FREE
  • Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_ALWAYS_NATIVE
  • Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
  • Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_NOT_NATIVE
  • Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_WAIT_FREE
  • Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_ALWAYS_NATIVE
  • Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
  • Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_NOT_NATIVE
  • Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_WAIT_FREE

For compatibility with previous versions of Qt, macros with an empty nn are equivalent to the 32-bit macros. For example, Q_ATOMIC_INT_REFERENCE_COUNTING_IS_WAIT_FREE is the same as Q_ATOMIC_INT32_REFERENCE_COUNTING_IS_WAIT_FREE.

See also QAtomicPointer.

Member Function Documentation

[constexpr noexcept] QAtomicInteger::QAtomicInteger(T value = 0)

Constructs a QAtomicInteger with the given value.

[noexcept] QAtomicInteger::QAtomicInteger(const QAtomicInteger<T> &other)

Constructs a copy of other.

bool QAtomicInteger::deref()

Atomically decrements the value of this QAtomicInteger. Returns true if the new value is non-zero, false otherwise.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

See also ref() and operator--().

T QAtomicInteger::fetchAndAddAcquire(T valueToAdd)

Atomic fetch-and-add.

Reads the current value of this QAtomicInteger and then adds valueToAdd to the current value, returning the original value.

This function uses acquire memory ordering semantics, which ensures that memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.

See also operator+=() and fetchAndSubAcquire().

T QAtomicInteger::fetchAndAddOrdered(T valueToAdd)

Atomic fetch-and-add.

Reads the current value of this QAtomicInteger and then adds valueToAdd to the current value, returning the original value.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

See also operator+=() and fetchAndSubOrdered().

T QAtomicInteger::fetchAndAddRelaxed(T valueToAdd)

Atomic fetch-and-add.

Reads the current value of this QAtomicInteger and then adds valueToAdd to the current value, returning the original value.

This function uses relaxed memory ordering semantics, leaving the compiler and processor to freely reorder memory accesses.

See also operator+=() and fetchAndSubRelaxed().

T QAtomicInteger::fetchAndAddRelease(T valueToAdd)

Atomic fetch-and-add.

Reads the current value of this QAtomicInteger and then adds valueToAdd to the current value, returning the original value.

This function uses release memory ordering semantics, which ensures that memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.

See also operator+=() and fetchAndSubRelease().

T QAtomicInteger::fetchAndAndAcquire(T valueToAnd)

Atomic fetch-and-and.

Reads the current value of this QAtomicInteger and then bitwise-ANDs valueToAnd to the current value, returning the original value.

This function uses acquire memory ordering semantics, which ensures that memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.

See also operator&=().

T QAtomicInteger::fetchAndAndOrdered(T valueToAnd)

Atomic fetch-and-and.

Reads the current value of this QAtomicInteger and then bitwise-ANDs valueToAnd to the current value, returning the original value.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

See also operator&=().

T QAtomicInteger::fetchAndAndRelaxed(T valueToAnd)

Atomic fetch-and-and.

Reads the current value of this QAtomicInteger and then bitwise-ANDs valueToAnd to the current value, returning the original value.

This function uses relaxed memory ordering semantics, leaving the compiler and processor to freely reorder memory accesses.

See also operator&=().

T QAtomicInteger::fetchAndAndRelease(T valueToAnd)

Atomic fetch-and-and.

Reads the current value of this QAtomicInteger and then bitwise-ANDs valueToAnd to the current value, returning the original value.

This function uses release memory ordering semantics, which ensures that memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.

See also operator&=().

T QAtomicInteger::fetchAndOrAcquire(T valueToOr)

Atomic fetch-and-or.

Reads the current value of this QAtomicInteger and then bitwise-ORs valueToOr to the current value, returning the original value.

This function uses acquire memory ordering semantics, which ensures that memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.

See also operator|=().

T QAtomicInteger::fetchAndOrOrdered(T valueToOr)

Atomic fetch-and-or.

Reads the current value of this QAtomicInteger and then bitwise-ORs valueToOr to the current value, returning the original value.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

See also operator|=().

T QAtomicInteger::fetchAndOrRelaxed(T valueToOr)

Atomic fetch-and-or.

Reads the current value of this QAtomicInteger and then bitwise-ORs valueToOr to the current value, returning the original value.

This function uses relaxed memory ordering semantics, leaving the compiler and processor to freely reorder memory accesses.

See also operator|=().

T QAtomicInteger::fetchAndOrRelease(T valueToOr)

Atomic fetch-and-or.

Reads the current value of this QAtomicInteger and then bitwise-ORs valueToOr to the current value, returning the original value.

This function uses release memory ordering semantics, which ensures that memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.

See also operator|=().

T QAtomicInteger::fetchAndStoreAcquire(T newValue)

Atomic fetch-and-store.

Reads the current value of this QAtomicInteger and then assigns it the newValue, returning the original value.

This function uses acquire memory ordering semantics, which ensures that memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.

T QAtomicInteger::fetchAndStoreOrdered(T newValue)

Atomic fetch-and-store.

Reads the current value of this QAtomicInteger and then assigns it the newValue, returning the original value.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

T QAtomicInteger::fetchAndStoreRelaxed(T newValue)

Atomic fetch-and-store.

Reads the current value of this QAtomicInteger and then assigns it the newValue, returning the original value.

This function uses relaxed memory ordering semantics, leaving the compiler and processor to freely reorder memory accesses.

T QAtomicInteger::fetchAndStoreRelease(T newValue)

Atomic fetch-and-store.

Reads the current value of this QAtomicInteger and then assigns it the newValue, returning the original value.

This function uses release memory ordering semantics, which ensures that memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.

T QAtomicInteger::fetchAndSubAcquire(T valueToSub)

Atomic fetch-and-sub.

Reads the current value of this QAtomicInteger and then subtracts valueToSub to the current value, returning the original value.

This function uses acquire memory ordering semantics, which ensures that memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.

See also operator-=() and fetchAndAddAcquire().

T QAtomicInteger::fetchAndSubOrdered(T valueToSub)

Atomic fetch-and-sub.

Reads the current value of this QAtomicInteger and then subtracts valueToSub to the current value, returning the original value.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

See also operator-=() and fetchAndAddOrdered().

T QAtomicInteger::fetchAndSubRelaxed(T valueToSub)

Atomic fetch-and-sub.

Reads the current value of this QAtomicInteger and then subtracts valueToSub to the current value, returning the original value.

This function uses relaxed memory ordering semantics, leaving the compiler and processor to freely reorder memory accesses.

See also operator-=() and fetchAndAddRelaxed().

T QAtomicInteger::fetchAndSubRelease(T valueToSub)

Atomic fetch-and-sub.

Reads the current value of this QAtomicInteger and then subtracts valueToSub to the current value, returning the original value.

This function uses release memory ordering semantics, which ensures that memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.

See also operator-=() and fetchAndAddRelease().

T QAtomicInteger::fetchAndXorAcquire(T valueToXor)

Atomic fetch-and-xor.

Reads the current value of this QAtomicInteger and then bitwise-XORs valueToXor to the current value, returning the original value.

This function uses acquire memory ordering semantics, which ensures that memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.

See also operator^=().

T QAtomicInteger::fetchAndXorOrdered(T valueToXor)

Atomic fetch-and-xor.

Reads the current value of this QAtomicInteger and then bitwise-XORs valueToXor to the current value, returning the original value.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

See also operator^=().

T QAtomicInteger::fetchAndXorRelaxed(T valueToXor)

Atomic fetch-and-xor.

Reads the current value of this QAtomicInteger and then bitwise-XORs valueToXor to the current value, returning the original value.

This function uses relaxed memory ordering semantics, leaving the compiler and processor to freely reorder memory accesses.

See also operator^=().

T QAtomicInteger::fetchAndXorRelease(T valueToXor)

Atomic fetch-and-xor.

Reads the current value of this QAtomicInteger and then bitwise-XORs valueToXor to the current value, returning the original value.

This function uses release memory ordering semantics, which ensures that memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.

See also operator^=().

[static constexpr] bool QAtomicInteger::isFetchAndAddNative()

Returns true if fetch-and-add is implemented using atomic processor instructions, false otherwise.

[static constexpr] bool QAtomicInteger::isFetchAndAddWaitFree()

Returns true if atomic fetch-and-add is wait-free, false otherwise.

[static constexpr] bool QAtomicInteger::isFetchAndStoreNative()

Returns true if fetch-and-store is implemented using atomic processor instructions, false otherwise.

[static constexpr] bool QAtomicInteger::isFetchAndStoreWaitFree()

Returns true if atomic fetch-and-store is wait-free, false otherwise.

[static constexpr] bool QAtomicInteger::isReferenceCountingNative()

Returns true if reference counting is implemented using atomic processor instructions, false otherwise.

[static constexpr] bool QAtomicInteger::isReferenceCountingWaitFree()

Returns true if atomic reference counting is wait-free, false otherwise.

[static constexpr] bool QAtomicInteger::isTestAndSetNative()

Returns true if test-and-set is implemented using atomic processor instructions, false otherwise.

[static constexpr] bool QAtomicInteger::isTestAndSetWaitFree()

Returns true if atomic test-and-set is wait-free, false otherwise.

T QAtomicInteger::loadAcquire() const

Atomically loads the value of this QAtomicInteger using the "Acquire" memory ordering. The value is not modified in any way, but note that there's no guarantee that it remains so.

See also storeRelaxed() and loadRelaxed().

T QAtomicInteger::loadRelaxed() const

Atomically loads the value of this QAtomicInteger using relaxed memory ordering. The value is not modified in any way, but note that there's no guarantee that it remains so.

See also storeRelaxed() and loadAcquire().

bool QAtomicInteger::ref()

Atomically increments the value of this QAtomicInteger. Returns true if the new value is non-zero, false otherwise.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

See also deref() and operator++().

void QAtomicInteger::storeRelaxed(T newValue)

Atomically stores the newValue value into this atomic type, using relaxed memory ordering.

See also storeRelease() and loadRelaxed().

void QAtomicInteger::storeRelease(T newValue)

Atomically stores the newValue value into this atomic type, using the "Release" memory ordering.

See also storeRelaxed() and loadAcquire().

bool QAtomicInteger::testAndSetAcquire(T expectedValue, T newValue)

Atomic test-and-set.

Note: If you use this function in a loop, consider using the overload with the additional T &currentValue argument instead, which avoids the extra load() on failure.

If the current value of this QAtomicInteger is the expectedValue, the test-and-set functions assign the newValue to this QAtomicInteger and return true. If the values are not the same, this function does nothing and returns false.

This function uses acquire memory ordering semantics, which ensures that memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.

bool QAtomicInteger::testAndSetAcquire(T expectedValue, T newValue, T &currentValue)

Atomic test-and-set.

If the current value of this QAtomicInteger is the expectedValue, the test-and-set functions assign the newValue to this QAtomicInteger and return true. If the values are not the same, the functions load the current value of this QAtomicInteger into currentValue and return false.

This function uses acquire memory ordering semantics, which ensures that memory access following the atomic operation (in program order) may not be re-ordered before the atomic operation.

bool QAtomicInteger::testAndSetOrdered(T expectedValue, T newValue)

Atomic test-and-set.

Note: If you use this function in a loop, consider using the overload with the additional T &currentValue argument instead, which avoids the extra load() on failure.

If the current value of this QAtomicInteger is the expectedValue, the test-and-set functions assign the newValue to this QAtomicInteger and return true. If the values are not the same, this function does nothing and returns false.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

bool QAtomicInteger::testAndSetOrdered(T expectedValue, T newValue, T &currentValue)

Atomic test-and-set.

If the current value of this QAtomicInteger is the expectedValue, the test-and-set functions assign the newValue to this QAtomicInteger and return true. If the values are not the same, it loads the current value of this QAtomicInteger into currentValue and return false.

This function uses ordered memory ordering semantics, which ensures that memory access before and after the atomic operation (in program order) may not be re-ordered.

bool QAtomicInteger::testAndSetRelaxed(T expectedValue, T newValue)

Atomic test-and-set.

Note: If you use this function in a loop, consider using the overload with the additional T &currentValue argument instead, which avoids the extra load() on failure.

If the current value of this QAtomicInteger is the expectedValue, the test-and-set functions assign the newValue to this QAtomicInteger and return true. If the values are not the same, this function does nothing and returns false.

This function uses relaxed memory ordering semantics, leaving the compiler and processor to freely reorder memory accesses.

bool QAtomicInteger::testAndSetRelaxed(T expectedValue, T newValue, T &currentValue)

Atomic test-and-set.

If the current value of this QAtomicInteger is the expectedValue, the test-and-set functions assign the newValue to this QAtomicInteger and return true. If the values are not the same, the functions load the current value of this QAtomicInteger into currentValue and return false.

This function uses relaxed memory ordering semantics, leaving the compiler and processor to freely reorder memory accesses.

bool QAtomicInteger::testAndSetRelease(T expectedValue, T newValue)

Atomic test-and-set.

Note: If you use this function in a loop, consider using the overload with the additional T &currentValue argument instead, which avoids the extra load() on failure.

If the current value of this QAtomicInteger is the expectedValue, the test-and-set functions assign the newValue to this QAtomicInteger and return true. If the values are not the same, this function does nothing and returns false.

This function uses release memory ordering semantics, which ensures that memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.

bool QAtomicInteger::testAndSetRelease(T expectedValue, T newValue, T &currentValue)

Atomic test-and-set.

If the current value of this QAtomicInteger is the expectedValue, the test-and-set functions assign the newValue to this QAtomicInteger and return true. If the values are not the same, the functions loads the current value of this QAtomicInteger into currentValue and return false.

This function uses release memory ordering semantics, which ensures that memory access before the atomic operation (in program order) may not be re-ordered after the atomic operation.

T QAtomicInteger::operator T() const

Atomically loads the value of this QAtomicInteger using a sequentially consistent memory ordering if possible; or "Acquire" ordering if not. The value is not modified in any way, but note that there's no guarantee that it remains so.

See also loadRelaxed() and loadAcquire().

T QAtomicInteger::operator&=(T value)

Atomic add-and-fetch.

Reads the current value of this QAtomicInteger and then bitwise-ANDs value to the current value, returning the new value.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also fetchAndAndOrdered().

T QAtomicInteger::operator++()

Atomically pre-increments the value of this QAtomicInteger. Returns the new value of this atomic.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also ref(), operator++(int), and operator--().

T QAtomicInteger::operator++(int)

Atomically post-increments the value of this QAtomicInteger. Returns the old value of this atomic.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also ref(), operator++(), and operator--(int).

T QAtomicInteger::operator+=(T value)

Atomic add-and-fetch.

Reads the current value of this QAtomicInteger and then adds value to the current value, returning the new value.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also fetchAndAddOrdered() and operator-=().

T QAtomicInteger::operator--()

Atomically pre-decrements the value of this QAtomicInteger. Returns the new value of this atomic.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also deref(), operator--(int), and operator++().

T QAtomicInteger::operator--(int)

Atomically post-decrements the value of this QAtomicInteger. Returns the old value of this atomic.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also deref(), operator--(), and operator++(int).

T QAtomicInteger::operator-=(T value)

Atomic sub-and-fetch.

Reads the current value of this QAtomicInteger and then subtracts value to the current value, returning the new value.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also fetchAndSubOrdered() and operator+=().

QAtomicInteger<T> &QAtomicInteger::operator=(T)

Atomically stores the other value into this atomic type using a sequentially consistent memory ordering if possible; or "Release" ordering if not. This function returns a reference to this object.

See also storeRelaxed() and storeRelease().

[noexcept] QAtomicInteger<T> &QAtomicInteger::operator=(const QAtomicInteger<T> &other)

Assigns other to this QAtomicInteger and returns a reference to this QAtomicInteger.

T QAtomicInteger::operator^=(T value)

Atomic xor-and-fetch.

Reads the current value of this QAtomicInteger and then bitwise-XORs value to the current value, returning the new value.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also fetchAndXorOrdered().

T QAtomicInteger::operator|=(T value)

Atomic or-and-fetch.

Reads the current value of this QAtomicInteger and then bitwise-ORs value to the current value, returning the new value.

This function uses a sequentially consistent memory ordering if possible; or "Ordered" ordering if not.

See also fetchAndOrOrdered().

Related Non-Members

[noexcept, since 6.7] void qYieldCpu()

Pauses the execution of the current thread for an unspecified time, using hardware instructions, without de-scheduling this thread. This function is meant to be used in high-throughput loops where the code expects another thread to modify an atomic variable. This is completely different from QThread::yieldCurrentThread(), which is an OS-level operation that may take the whole thread off the CPU and allow other threads (possibly belonging to other processes) to run.

So, instead of

while (!condition)
    ;

one should write

while (!condition)
    qYieldCpu();

This is useful both with and without hardware multithreading on the same core. In the case of hardware threads, it serves to prevent further speculative execution filling up the pipeline, which could starve the sibling thread of resources. Across cores and higher levels of separation, it allows the cache coherency protocol to allocate the cache line being modified and inspected to the logical processor whose result this code is expecting.

It is also recommended to loop around code that does not modify the global variable, to avoid contention in exclusively obtaining the memory location. Therefore, an atomic modification loop such as a spinlock acquisition should be:

while (true) {
    while (!readOnlyCondition(atomic))
        qYieldCpu();
    if (modify(atomic))
        break;
}

On x86 processors and on RISC-V processors with the Zihintpause extension, this will emit the PAUSE instruction, which is ignored on processors that don't support it; on ARMv7 or later ARM processors, it will emit the YIELD instruction.

This function was introduced in Qt 6.7.

Macro Documentation

Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_ALWAYS_NATIVE

This macro is defined if and only if your processor supports atomic fetch-and-add on integers.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_NOT_NATIVE

This macro is defined when the hardware does not support atomic fetch-and-add on integers.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

This macro is defined when only certain generations of the processor support atomic fetch-and-add on integers. Use the QAtomicInteger<T>::isFetchAndAddNative() function to check what your processor supports.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_WAIT_FREE

This macro is defined together with Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_ALWAYS_NATIVE to indicate that the atomic fetch-and-add on integers is wait-free.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_ALWAYS_NATIVE

This macro is defined if and only if your processor supports atomic fetch-and-store on integers.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_NOT_NATIVE

This macro is defined when the hardware does not support atomic fetch-and-store on integers.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

This macro is defined when only certain generations of the processor support atomic fetch-and-store on integers. Use the QAtomicInteger<T>::isFetchAndStoreNative() function to check what your processor supports.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_WAIT_FREE

This macro is defined together with Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_ALWAYS_NATIVE to indicate that the atomic fetch-and-store on integers is wait-free.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_IS_SUPPORTED

This macro is defined if atomic integers of size nn (in bits) are supported in this compiler / architecture combination.

nn is the size of the integer, in bits (8, 16, 32 or 64).

The following macros always defined:

  • Q_ATOMIC_INT8_IS_SUPPORTED
  • Q_ATOMIC_INT16_IS_SUPPORTED
  • Q_ATOMIC_INT32_IS_SUPPORTED

Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_ALWAYS_NATIVE

This macro is defined if and only if all generations of your processor support atomic reference counting.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_NOT_NATIVE

This macro is defined when the hardware does not support atomic reference counting.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE

This macro is defined when only certain generations of the processor support atomic reference counting. Use the QAtomicInteger<T>::isReferenceCountingNative() function to check what your processor supports.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_WAIT_FREE

This macro is defined together with Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_ALWAYS_NATIVE to indicate that the reference counting is wait-free.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_TEST_AND_SET_IS_ALWAYS_NATIVE

This macro is defined if and only if your processor supports atomic test-and-set on integers.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_TEST_AND_SET_IS_NOT_NATIVE

This macro is defined when the hardware does not support atomic test-and-set on integers.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_TEST_AND_SET_IS_SOMETIMES_NATIVE

This macro is defined when only certain generations of the processor support atomic test-and-set on integers. Use the QAtomicInteger<T>::isTestAndSetNative() function to check what your processor supports.

nn is the size of the integer, in bits (8, 16, 32 or 64).

Q_ATOMIC_INTnn_TEST_AND_SET_IS_WAIT_FREE

This macro is defined together with Q_ATOMIC_INTnn_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that the atomic test-and-set on integers is wait-free.

nn is the size of the integer, in bits (8, 16, 32 or 64).

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.