qt/qtbase/src/corelib/thread/qatomic.cpp

Revision control

++ // Copyright (C) 2016 The Qt Company Ltd.
++ // Copyright (C) 2016 Intel Corporation.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
++ // Qt-Security score:significant reason:default
++
++ #include "qatomic.h"
++
++ /*!
++ \class QAtomicInt
++ \inmodule QtCore
++ \brief The QAtomicInt class provides platform-independent atomic operations on int.
++ \since 4.4
++
++ This class is a equivalent to \c{QAtomicInteger<int>}. All other
++ functionality is equivalent. Please see that class for more information.
++
++ \sa QAtomicInteger, QAtomicPointer
++ */
++
++ /*!
++ \class QAtomicInteger
++ \inmodule QtCore
++ \brief The QAtomicInteger class provides platform-independent atomic operations on integers.
++ \ingroup thread
++ \since 5.3
++
++ For atomic operations on pointers, see the QAtomicPointer class.
++
++ An \e 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 \a T specifies the integer type
++ being made atomic.
++
++ The template parameter \a T must be a C++ integer type:
++ \list
++ \li 8-bit: bool, char, signed char, unsigned char, qint8, quint8, char8_t (C++20)
++ \li 16-bit: short, unsigned short, qint16, quint16, char16_t
++ \li 32-bit: int, unsigned int, qint32, quint32, char32_t
++ \li 64-bit: long long, unsigned long long, qint64, quint64
++ \li platform-specific size: long, unsigned long
++ \li pointer size: qintptr, quintptr, qptrdiff
++ \endlist
++
++ 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 \c Q_ATOMIC_INT64_IS_SUPPORTED.
++
++ \section1 The Atomic API
++
++ \section2 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.
++
++ \snippet code/src_corelib_thread_qatomic.cpp 0
++
++ \section2 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.
++
++ \list
++
++ \li Relaxed - memory ordering is unspecified, leaving the compiler
++ and processor to freely reorder memory accesses.
++
++ \li Acquire - memory access following the atomic operation (in
++ program order) may not be re-ordered before the atomic operation.
++
++ \li Release - memory access before the atomic operation (in program
++ order) may not be re-ordered after the atomic operation.
++
++ \li Ordered - the same Acquire and Release semantics combined.
++
++ \endlist
++
++ \section2 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 \e not the same, these functions do
++ nothing and return false. This operation equates to the following
++ code:
++
++ \snippet code/src_corelib_thread_qatomic.cpp 1
++
++ There are 4 test-and-set functions: testAndSetRelaxed(),
++ testAndSetAcquire(), testAndSetRelease(), and
++ testAndSetOrdered(). See above for an explanation of the different
++ memory ordering semantics.
++
++ \section2 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:
++
++ \snippet code/src_corelib_thread_qatomic.cpp 2
++
++ There are 4 fetch-and-store functions: fetchAndStoreRelaxed(),
++ fetchAndStoreAcquire(), fetchAndStoreRelease(), and
++ fetchAndStoreOrdered(). See above for an explanation of the
++ different memory ordering semantics.
++
++ \section2 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:
++
++ \snippet code/src_corelib_thread_qatomic.cpp 3
++
++ There are 4 fetch-and-add functions: fetchAndAddRelaxed(),
++ fetchAndAddAcquire(), fetchAndAddRelease(), and
++ fetchAndAddOrdered(). See above for an explanation of the
++ different memory ordering semantics.
++
++ \section1 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_INT\e{nn}_\e{OPERATION}_IS_\e{HOW}_NATIVE. \e{nn} is the
++ size of the integer (in bits), \e{OPERATION}
++ is one of REFERENCE_COUNTING, TEST_AND_SET,
++ FETCH_AND_STORE, or FETCH_AND_ADD, and \e{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_INT\e{nn}_\e{OPERATION}_IS_WAIT_FREE in addition to the
++ Q_ATOMIC_INT\e{nn}_\e{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:
++
++ \list
++
++ \li Q_ATOMIC_INT\e{nn}_REFERENCE_COUNTING_IS_ALWAYS_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_REFERENCE_COUNTING_IS_NOT_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_REFERENCE_COUNTING_IS_WAIT_FREE
++
++ \li Q_ATOMIC_INT\e{nn}_TEST_AND_SET_IS_ALWAYS_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_TEST_AND_SET_IS_SOMETIMES_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_TEST_AND_SET_IS_NOT_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_TEST_AND_SET_IS_WAIT_FREE
++
++ \li Q_ATOMIC_INT\e{nn}_FETCH_AND_STORE_IS_ALWAYS_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_FETCH_AND_STORE_IS_NOT_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_FETCH_AND_STORE_IS_WAIT_FREE
++
++ \li Q_ATOMIC_INT\e{nn}_FETCH_AND_ADD_IS_ALWAYS_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_FETCH_AND_ADD_IS_NOT_NATIVE
++ \li Q_ATOMIC_INT\e{nn}_FETCH_AND_ADD_IS_WAIT_FREE
++
++ \endlist
++
++ For compatibility with previous versions of Qt, macros with an empty \e{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.
++
++ \sa QAtomicPointer
++ */
++
++ /*!
++ \fn QAtomicInt::QAtomicInt(int value)
++
++ Constructs a QAtomicInt with the given \a value.
++ */
++
++ /*!
++ \fn template <typename T> QAtomicInteger<T>::QAtomicInteger(T value)
++
++ Constructs a QAtomicInteger with the given \a value.
++ */
++
++ /*!
++ \fn template <typename T> QAtomicInteger<T>::QAtomicInteger(const QAtomicInteger &other)
++
++ Constructs a copy of \a other.
++ */
++
++ /*!
++ \fn template <typename T> QAtomicInteger &QAtomicInteger<T>::operator=(const QAtomicInteger &other)
++
++ Assigns \a other to this QAtomicInteger and returns a reference to
++ this QAtomicInteger.
++ */
++
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::loadRelaxed() const
++ \since 5.14
++
++ 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.
++
++ \sa storeRelaxed(), loadAcquire()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::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.
++
++ \sa storeRelaxed(), loadRelaxed()
++ */
++
++ /*!
++ \fn template <typename T> void QAtomicInteger<T>::storeRelaxed(T newValue)
++ \since 5.14
++
++ Atomically stores the \a newValue value into this atomic type, using
++ relaxed memory ordering.
++
++ \sa storeRelease(), loadRelaxed()
++ */
++
++ /*!
++ \fn template <typename T> void QAtomicInteger<T>::storeRelease(T newValue)
++
++ Atomically stores the \a newValue value into this atomic type, using
++ the "Release" memory ordering.
++
++ \sa storeRelaxed(), loadAcquire()
++ */
++
++ /*!
++ \fn template <typename T> QAtomicInteger<T>::operator T() const
++ \since 5.3
++
++ 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.
++
++ \sa loadRelaxed(), loadAcquire()
++ */
++
++ /*!
++ \fn template <typename T> QAtomicInteger &QAtomicInteger<T>::operator=(T)
++ \since 5.3
++
++ 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.
++
++ \sa storeRelaxed(), storeRelease()
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::isReferenceCountingNative()
++
++ Returns \c true if reference counting is implemented using atomic
++ processor instructions, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::isReferenceCountingWaitFree()
++
++ Returns \c true if atomic reference counting is wait-free, false
++ otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::ref()
++ Atomically increments the value of this QAtomicInteger. Returns \c true
++ if the new value is non-zero, false otherwise.
++
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++
++ \sa deref(), operator++()
++ */
++
++ /*!
++ \fn template <typename T> void QAtomicInteger<T>::refRelaxed()
++ \internal
++ Atomically increments the value of this QAtomicInteger.
++
++ In contrast to ref(), this uses relaxed semantics, which is
++ all that is needed for reference counting (together with deref's
++ acquire-release semantics).
++ It also doesn't return anything.
++
++ \sa deref(), operator++()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator++()
++ \since 5.3
++
++ 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.
++
++ \sa ref(), operator++(int), operator--()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator++(int)
++ \since 5.3
++
++ 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.
++
++ \sa ref(), operator++(), operator--(int)
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::deref()
++ Atomically decrements the value of this QAtomicInteger. Returns \c true
++ if the new value is non-zero, false otherwise.
++
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++
++ \sa ref(), operator--()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator--()
++ \since 5.3
++
++ 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.
++
++ \sa deref(), operator--(int), operator++()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator--(int)
++ \since 5.3
++
++ 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.
++
++ \sa deref(), operator--(), operator++(int)
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::isTestAndSetNative()
++
++ Returns \c true if test-and-set is implemented using atomic processor
++ instructions, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::isTestAndSetWaitFree()
++
++ Returns \c true if atomic test-and-set is wait-free, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::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 \c{T &currentValue} argument instead, which avoids the extra loadRelaxed() on
++ failure.
++
++ If the current value of this QAtomicInteger is the \a expectedValue,
++ the test-and-set functions assign the \a newValue to this
++ QAtomicInteger and return true. If the values are \e not the same,
++ this function does nothing and returns \c false.
++
++ //![memory-order-relaxed]
++ This function uses \e relaxed \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++ //![memory-order-relaxed]
++
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::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 \c{T &currentValue} argument instead, which avoids the extra loadAcquire() on
++ failure.
++
++ If the current value of this QAtomicInteger is the \a expectedValue,
++ the test-and-set functions assign the \a newValue to this
++ QAtomicInteger and return true. If the values are \e not the same,
++ this function does nothing and returns \c false.
++
++ //![memory-order-acquire]
++ This function uses \e acquire \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++ //![memory-order-acquire]
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::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 \c{T &currentValue} argument instead, which avoids the extra loadRelaxed() on
++ failure.
++
++ If the current value of this QAtomicInteger is the \a expectedValue,
++ the test-and-set functions assign the \a newValue to this
++ QAtomicInteger and return true. If the values are \e not the same,
++ this function does nothing and returns \c false.
++
++ //![memory-order-release]
++ This function uses \e release \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++ //![memory-order-release]
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::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 \c{T &currentValue} argument instead, which avoids the extra loadAcquire() on
++ failure.
++
++ If the current value of this QAtomicInteger is the \a expectedValue,
++ the test-and-set functions assign the \a newValue to this
++ QAtomicInteger and return true. If the values are \e not the same,
++ this function does nothing and returns \c false.
++
++ //![memory-order-ordered]
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++ //![memory-order-ordered]
++
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::testAndSetRelaxed(T expectedValue, T newValue, T &currentValue)
++ \since 5.3
++
++ Atomic test-and-set.
++
++ If the current value of this QAtomicInteger is the \a expectedValue, the
++ test-and-set functions assign the \a newValue to this QAtomicInteger and
++ return \c true. If the values are \e not the same, the functions load the
++ current value of this QAtomicInteger into \a currentValue and return \c false.
++
++ //![memory-order-3-arg-relaxed]
++ \include qatomic.cpp memory-order-relaxed
++ If the test-and-set fails, the \a currentValue is loaded with \e relaxed
++ \l {QAtomicInteger#Memory ordering}{memory ordering} semantics.
++ //![memory-order-3-arg-relaxed]
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::testAndSetAcquire(T expectedValue, T newValue, T &currentValue)
++ \since 5.3
++
++ Atomic test-and-set.
++
++ If the current value of this QAtomicInteger is the \a expectedValue, the
++ test-and-set functions assign the \a newValue to this QAtomicInteger and
++ return \c true. If the values are \e not the same, the functions load the
++ current value of this QAtomicInteger into \a currentValue and return \c false.
++
++ //![memory-order-3-arg-acquire]
++ \include qatomic.cpp memory-order-acquire
++ If the test-and-set fails, the \a currentValue is loaded with \e acquire
++ \l {QAtomicInteger#Memory ordering}{memory ordering} semantics.
++ //![memory-order-3-arg-acquire]
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::testAndSetRelease(T expectedValue, T newValue, T &currentValue)
++ \since 5.3
++
++ Atomic test-and-set.
++
++ If the current value of this QAtomicInteger is the \a expectedValue, the
++ test-and-set functions assign the \a newValue to this QAtomicInteger and
++ return \c true. If the values are \e not the same, the functions loads the
++ current value of this QAtomicInteger into \a currentValue and return \c false.
++
++ //![memory-order-3-arg-release]
++ \include qatomic.cpp memory-order-release
++ If the test-and-set fails, the \a currentValue is loaded with \e relaxed
++ \l {QAtomicInteger#Memory ordering}{memory ordering} semantics.
++ //![memory-order-3-arg-release]
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::testAndSetOrdered(T expectedValue, T newValue, T &currentValue)
++ \since 5.3
++
++ Atomic test-and-set.
++
++ If the current value of this QAtomicInteger is the \a expectedValue, the
++ test-and-set functions assign the \a newValue to this QAtomicInteger and
++ return \c true. If the values are \e not the same, it loads the current
++ value of this QAtomicInteger into \a currentValue and return \c false.
++
++ //![memory-order-3-arg-ordered]
++ \include qatomic.cpp memory-order-ordered
++ If the test-and-set fails, the \a currentValue is loaded with \e acquire
++ \l {QAtomicInteger#Memory ordering}{memory ordering} semantics.
++ //![memory-order-3-arg-ordered]
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::isFetchAndStoreNative()
++
++ Returns \c true if fetch-and-store is implemented using atomic
++ processor instructions, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::isFetchAndStoreWaitFree()
++
++ Returns \c true if atomic fetch-and-store is wait-free, false
++ otherwise.
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndStoreRelaxed(T newValue)
++
++ Atomic fetch-and-store.
++
++ Reads the current value of this QAtomicInteger and then assigns it the
++ \a newValue, returning the original value.
++
++ This function uses \e relaxed \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndStoreAcquire(T newValue)
++
++ Atomic fetch-and-store.
++
++ Reads the current value of this QAtomicInteger and then assigns it the
++ \a newValue, returning the original value.
++
++ This function uses \e acquire \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndStoreRelease(T newValue)
++
++ Atomic fetch-and-store.
++
++ Reads the current value of this QAtomicInteger and then assigns it the
++ \a newValue, returning the original value.
++
++ This function uses \e release \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndStoreOrdered(T newValue)
++
++ Atomic fetch-and-store.
++
++ Reads the current value of this QAtomicInteger and then assigns it the
++ \a newValue, returning the original value.
++
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::isFetchAndAddNative()
++
++ Returns \c true if fetch-and-add is implemented using atomic
++ processor instructions, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicInteger<T>::isFetchAndAddWaitFree()
++
++ Returns \c true if atomic fetch-and-add is wait-free, false
++ otherwise.
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndAddRelaxed(T valueToAdd)
++
++ Atomic fetch-and-add.
++
++ Reads the current value of this QAtomicInteger and then adds
++ \a valueToAdd to the current value, returning the original value.
++
++ This function uses \e relaxed \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++
++ \sa operator+=(), fetchAndSubRelaxed()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndAddAcquire(T valueToAdd)
++
++ Atomic fetch-and-add.
++
++ Reads the current value of this QAtomicInteger and then adds
++ \a valueToAdd to the current value, returning the original value.
++
++ This function uses \e acquire \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++
++ \sa operator+=(), fetchAndSubAcquire()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndAddRelease(T valueToAdd)
++
++ Atomic fetch-and-add.
++
++ Reads the current value of this QAtomicInteger and then adds
++ \a valueToAdd to the current value, returning the original value.
++
++ This function uses \e release \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++
++ \sa operator+=(), fetchAndSubRelease()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndAddOrdered(T valueToAdd)
++
++ Atomic fetch-and-add.
++
++ Reads the current value of this QAtomicInteger and then adds
++ \a valueToAdd to the current value, returning the original value.
++
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++
++ \sa operator+=(), fetchAndSubOrdered()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator+=(T value)
++ \since 5.3
++
++ Atomic add-and-fetch.
++
++ Reads the current value of this QAtomicInteger and then adds
++ \a value to the current value, returning the new value.
++
++ This function uses a sequentially consistent memory ordering if possible;
++ or "Ordered" ordering if not.
++
++ \sa fetchAndAddOrdered(), operator-=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndSubRelaxed(T valueToSub)
++ \since 5.3
++
++ Atomic fetch-and-sub.
++
++ Reads the current value of this QAtomicInteger and then subtracts
++ \a valueToSub to the current value, returning the original value.
++
++ This function uses \e relaxed \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++
++ \sa operator-=(), fetchAndAddRelaxed()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndSubAcquire(T valueToSub)
++ \since 5.3
++
++ Atomic fetch-and-sub.
++
++ Reads the current value of this QAtomicInteger and then subtracts
++ \a valueToSub to the current value, returning the original value.
++
++ This function uses \e acquire \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++
++ \sa operator-=(), fetchAndAddAcquire()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndSubRelease(T valueToSub)
++ \since 5.3
++
++ Atomic fetch-and-sub.
++
++ Reads the current value of this QAtomicInteger and then subtracts
++ \a valueToSub to the current value, returning the original value.
++
++ This function uses \e release \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++
++ \sa operator-=(), fetchAndAddRelease()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndSubOrdered(T valueToSub)
++ \since 5.3
++
++ Atomic fetch-and-sub.
++
++ Reads the current value of this QAtomicInteger and then subtracts
++ \a valueToSub to the current value, returning the original value.
++
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++
++ \sa operator-=(), fetchAndAddOrdered()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator-=(T value)
++ \since 5.3
++
++ Atomic sub-and-fetch.
++
++ Reads the current value of this QAtomicInteger and then subtracts
++ \a value to the current value, returning the new value.
++
++ This function uses a sequentially consistent memory ordering if possible;
++ or "Ordered" ordering if not.
++
++ \sa fetchAndSubOrdered(), operator+=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndOrRelaxed(T valueToOr)
++ \since 5.3
++
++ Atomic fetch-and-or.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ORs
++ \a valueToOr to the current value, returning the original value.
++
++ This function uses \e relaxed \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++
++ \sa operator|=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndOrAcquire(T valueToOr)
++ \since 5.3
++
++ Atomic fetch-and-or.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ORs
++ \a valueToOr to the current value, returning the original value.
++
++ This function uses \e acquire \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++
++ \sa operator|=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndOrRelease(T valueToOr)
++ \since 5.3
++
++ Atomic fetch-and-or.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ORs
++ \a valueToOr to the current value, returning the original value.
++
++ This function uses \e release \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++
++ \sa operator|=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndOrOrdered(T valueToOr)
++ \since 5.3
++
++ Atomic fetch-and-or.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ORs
++ \a valueToOr to the current value, returning the original value.
++
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++
++ \sa operator|=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator|=(T value)
++ \since 5.3
++
++ Atomic or-and-fetch.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ORs
++ \a value to the current value, returning the new value.
++
++ This function uses a sequentially consistent memory ordering if possible;
++ or "Ordered" ordering if not.
++
++ \sa fetchAndOrOrdered()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndXorRelaxed(T valueToXor)
++ \since 5.3
++
++ Atomic fetch-and-xor.
++
++ Reads the current value of this QAtomicInteger and then bitwise-XORs
++ \a valueToXor to the current value, returning the original value.
++
++ This function uses \e relaxed \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++
++ \sa operator^=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndXorAcquire(T valueToXor)
++ \since 5.3
++
++ Atomic fetch-and-xor.
++
++ Reads the current value of this QAtomicInteger and then bitwise-XORs
++ \a valueToXor to the current value, returning the original value.
++
++ This function uses \e acquire \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++
++ \sa operator^=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndXorRelease(T valueToXor)
++ \since 5.3
++
++ Atomic fetch-and-xor.
++
++ Reads the current value of this QAtomicInteger and then bitwise-XORs
++ \a valueToXor to the current value, returning the original value.
++
++ This function uses \e release \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++
++ \sa operator^=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndXorOrdered(T valueToXor)
++ \since 5.3
++
++ Atomic fetch-and-xor.
++
++ Reads the current value of this QAtomicInteger and then bitwise-XORs
++ \a valueToXor to the current value, returning the original value.
++
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++
++ \sa operator^=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator^=(T value)
++ \since 5.3
++
++ Atomic xor-and-fetch.
++
++ Reads the current value of this QAtomicInteger and then bitwise-XORs
++ \a value to the current value, returning the new value.
++
++ This function uses a sequentially consistent memory ordering if possible;
++ or "Ordered" ordering if not.
++
++ \sa fetchAndXorOrdered()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndAndRelaxed(T valueToAnd)
++ \since 5.3
++
++ Atomic fetch-and-and.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ANDs
++ \a valueToAnd to the current value, returning the original value.
++
++ This function uses \e relaxed \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++
++ \sa operator&=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndAndAcquire(T valueToAnd)
++ \since 5.3
++
++ Atomic fetch-and-and.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ANDs
++ \a valueToAnd to the current value, returning the original value.
++
++ This function uses \e acquire \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++
++ \sa operator&=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndAndRelease(T valueToAnd)
++ \since 5.3
++
++ Atomic fetch-and-and.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ANDs
++ \a valueToAnd to the current value, returning the original value.
++
++ This function uses \e release \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++
++ \sa operator&=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::fetchAndAndOrdered(T valueToAnd)
++ \since 5.3
++
++ Atomic fetch-and-and.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ANDs
++ \a valueToAnd to the current value, returning the original value.
++
++ This function uses \e ordered \l {QAtomicInteger#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++
++ \sa operator&=()
++ */
++
++ /*!
++ \fn template <typename T> T QAtomicInteger<T>::operator&=(T value)
++ \since 5.3
++
++ Atomic add-and-fetch.
++
++ Reads the current value of this QAtomicInteger and then bitwise-ANDs
++ \a value to the current value, returning the new value.
++
++ This function uses a sequentially consistent memory ordering if possible;
++ or "Ordered" ordering if not.
++
++ \sa fetchAndAndOrdered()
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_IS_SUPPORTED
++ \relates QAtomicInteger
++
++ This macro is defined if atomic integers of size \e{nn} (in bits) are
++ supported in this compiler / architecture combination.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++
++ The following macros always defined:
++
++ \list
++ \li Q_ATOMIC_INT8_IS_SUPPORTED
++ \li Q_ATOMIC_INT16_IS_SUPPORTED
++ \li Q_ATOMIC_INT32_IS_SUPPORTED
++ \endlist
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_ALWAYS_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined if and only if all generations of your
++ processor support atomic reference counting.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined when only certain generations of the
++ processor support atomic reference counting. Use the
++ QAtomicInteger::isReferenceCountingNative() function to check what
++ your processor supports.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_NOT_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined when the hardware does not support atomic
++ reference counting.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_WAIT_FREE
++ \relates QAtomicInteger
++
++ This macro is defined together with
++ Q_ATOMIC_INTnn_REFERENCE_COUNTING_IS_ALWAYS_NATIVE to indicate that
++ the reference counting is wait-free.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_TEST_AND_SET_IS_ALWAYS_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined if and only if your processor supports
++ atomic test-and-set on integers.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_TEST_AND_SET_IS_SOMETIMES_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined when only certain generations of the
++ processor support atomic test-and-set on integers. Use the
++ QAtomicInteger::isTestAndSetNative() function to check what your
++ processor supports.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_TEST_AND_SET_IS_NOT_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined when the hardware does not support atomic
++ test-and-set on integers.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_TEST_AND_SET_IS_WAIT_FREE
++ \relates QAtomicInteger
++
++ 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.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_ALWAYS_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined if and only if your processor supports
++ atomic fetch-and-store on integers.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined when only certain generations of the
++ processor support atomic fetch-and-store on integers. Use the
++ QAtomicInteger::isFetchAndStoreNative() function to check what your
++ processor supports.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_NOT_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined when the hardware does not support atomic
++ fetch-and-store on integers.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_FETCH_AND_STORE_IS_WAIT_FREE
++ \relates QAtomicInteger
++
++ 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.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_ALWAYS_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined if and only if your processor supports
++ atomic fetch-and-add on integers.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined when only certain generations of the
++ processor support atomic fetch-and-add on integers. Use the
++ QAtomicInteger::isFetchAndAddNative() function to check what your
++ processor supports.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_NOT_NATIVE
++ \relates QAtomicInteger
++
++ This macro is defined when the hardware does not support atomic
++ fetch-and-add on integers.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++ /*!
++ \macro Q_ATOMIC_INTnn_FETCH_AND_ADD_IS_WAIT_FREE
++ \relates QAtomicInteger
++
++ 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.
++
++ \e{nn} is the size of the integer, in bits (8, 16, 32 or 64).
++ */
++
++
++
++
++ /*!
++ \class QAtomicPointer
++ \inmodule QtCore
++ \brief The QAtomicPointer class is a template class that provides platform-independent atomic operations on pointers.
++ \since 4.4
++
++ \ingroup thread
++
++ For atomic operations on integers, see the QAtomicInteger class.
++
++ An \e atomic operation is a complex operation that completes without interruption.
++ The QAtomicPointer class provides atomic test-and-set, fetch-and-store, and fetch-and-add
++ for pointers. The template parameter \a T specifies the pointed-to type.
++
++ \section1 The Atomic API
++
++ \section2 Memory ordering
++
++ QAtomicPointer 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.
++
++ \list
++
++ \li Relaxed - memory ordering is unspecified, leaving the compiler
++ and processor to freely reorder memory accesses.
++
++ \li Acquire - memory access following the atomic operation (in
++ program order) may not be re-ordered before the atomic operation.
++
++ \li Release - memory access before the atomic operation (in program
++ order) may not be re-ordered after the atomic operation.
++
++ \li Ordered - the same Acquire and Release semantics combined.
++
++ \endlist
++
++ \section2 Test-and-set
++
++ If the current value of the QAtomicPointer is an expected value,
++ the test-and-set functions assign a new value to the
++ QAtomicPointer and return true. If values are \e not the same,
++ these functions do nothing and return false. This operation
++ equates to the following code:
++
++ \snippet code/src_corelib_thread_qatomic.cpp 4
++
++ There are 4 test-and-set functions: testAndSetRelaxed(),
++ testAndSetAcquire(), testAndSetRelease(), and
++ testAndSetOrdered(). See above for an explanation of the different
++ memory ordering semantics.
++
++ \section2 Fetch-and-store
++
++ The atomic fetch-and-store functions read the current value of the
++ QAtomicPointer and then assign a new value, returning the original
++ value. This operation equates to the following code:
++
++ \snippet code/src_corelib_thread_qatomic.cpp 5
++
++ There are 4 fetch-and-store functions: fetchAndStoreRelaxed(),
++ fetchAndStoreAcquire(), fetchAndStoreRelease(), and
++ fetchAndStoreOrdered(). See above for an explanation of the
++ different memory ordering semantics.
++
++ \section2 Fetch-and-add
++
++ The atomic fetch-and-add functions read the current value of the
++ QAtomicPointer and then add the given value to the current value,
++ returning the original value. This operation equates to the
++ following code:
++
++ \snippet code/src_corelib_thread_qatomic.cpp 6
++
++ There are 4 fetch-and-add functions: fetchAndAddRelaxed(),
++ fetchAndAddAcquire(), fetchAndAddRelease(), and
++ fetchAndAddOrdered(). See above for an explanation of the
++ different memory ordering semantics.
++
++ \section1 Feature Tests for the Atomic API
++
++ Providing a platform-independent atomic API that works on all
++ processors is challenging. The API provided by QAtomicPointer is
++ guaranteed to work atomically on all processors. However, since
++ not all processors implement support for every operation provided
++ by QAtomicPointer, 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_POINTER_\e{OPERATION}_IS_\e{HOW}_NATIVE. \e{OPERATION} is
++ one of TEST_AND_SET, FETCH_AND_STORE, or FETCH_AND_ADD, and
++ \e{HOW} is one of ALWAYS, SOMETIMES, or NOT. There will always be
++ exactly one defined macro per operation. For example, if
++ Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE is defined, neither
++ Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE nor
++ Q_ATOMIC_POINTER_TEST_AND_SET_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_POINTER_\e{OPERATION}_IS_WAIT_FREE in addition to the
++ Q_ATOMIC_POINTER_\e{OPERATION}_IS_ALWAYS_NATIVE.
++
++ In cases where an atomic operation is only supported in newer
++ generations of the processor, QAtomicPointer also provides a way
++ to check at runtime what your hardware supports with the
++ isTestAndSetNative(), isFetchAndStoreNative(), and
++ isFetchAndAddNative() functions. Wait-free implementations can be
++ detected using the isTestAndSetWaitFree(),
++ isFetchAndStoreWaitFree(), and isFetchAndAddWaitFree() functions.
++
++ Below is a complete list of all feature macros for QAtomicPointer:
++
++ \list
++
++ \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
++ \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
++ \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
++ \li Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
++
++ \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
++ \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
++ \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
++ \li Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
++
++ \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
++ \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
++ \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
++ \li Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
++
++ \endlist
++
++ \sa QAtomicInteger, qYieldCpu()
++ */
++
++ /*!
++ \fn template <typename T> QAtomicPointer<T>::QAtomicPointer(T *value)
++
++ Constructs a QAtomicPointer with the given \a value.
++ */
++
++ /*!
++ \fn template <typename T> QAtomicPointer<T>::QAtomicPointer(const QAtomicPointer<T> &other)
++
++ Constructs a copy of \a other.
++ */
++
++ /*!
++ \fn template <typename T> QAtomicPointer &QAtomicPointer<T>::operator=(const QAtomicPointer &other)
++
++ Assigns \a other to this QAtomicPointer and returns a reference to
++ this QAtomicPointer.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::loadRelaxed() const
++ \since 5.14
++
++ Atomically loads the value of this QAtomicPointer using relaxed memory
++ ordering. The value is not modified in any way, but note that there's no
++ guarantee that it remains so.
++
++ \sa storeRelaxed(), loadAcquire()
++ */
++
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::loadAcquire() const
++
++ Atomically loads the value of this QAtomicPointer using the "Acquire" memory
++ ordering. The value is not modified in any way, but note that there's no
++ guarantee that it remains so.
++
++ \sa storeRelease(), loadRelaxed()
++ */
++
++ /*!
++ \fn template <typename T> void QAtomicPointer<T>::storeRelaxed(T *newValue)
++ \since 5.14
++
++ Atomically stores the \a newValue value into this atomic type, using
++ relaxed memory ordering.
++
++ \sa storeRelease(), loadRelaxed()
++ */
++
++ /*!
++ \fn template <typename T> void QAtomicPointer<T>::storeRelease(T *newValue)
++
++ Atomically stores the \a newValue value into this atomic type, using
++ the "Release" memory ordering.
++
++ \sa storeRelaxed(), loadRelaxed()
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::isTestAndSetNative()
++
++ Returns \c true if test-and-set is implemented using atomic processor
++ instructions, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::isTestAndSetWaitFree()
++
++ Returns \c true if atomic test-and-set is wait-free, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::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 \c{T *&currentValue} argument instead, which avoids the extra load() on
++ failure.
++
++ If the current value of this QAtomicPointer is the \a expectedValue,
++ the test-and-set functions assign the \a newValue to this
++ QAtomicPointer and return true. If the values are \e not the same,
++ this function does nothing and returns \c false.
++
++ This function uses \e relaxed \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::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 \c{T *&currentValue} argument instead, which avoids the extra load() on
++ failure.
++
++ If the current value of this QAtomicPointer is the \a expectedValue,
++ the test-and-set functions assign the \a newValue to this
++ QAtomicPointer and return true. If the values are \e not the same,
++ this function does nothing and returns \c false.
++
++ This function uses \e acquire \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::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 \c{T *&currentValue} argument instead, which avoids the extra load() on
++ failure.
++
++ If the current value of this QAtomicPointer is the \a expectedValue,
++ the test-and-set functions assign the \a newValue to this
++ QAtomicPointer and return true. If the values are \e not the same,
++ this function does nothing and returns \c false.
++
++ This function uses \e release \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::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 \c{T *&currentValue} argument instead, which avoids the extra load() on
++ failure.
++
++ If the current value of this QAtomicPointer is the \a expectedValue,
++ the test-and-set functions assign the \a newValue to this
++ QAtomicPointer and return true. If the values are \e not the same,
++ this function does nothing and returns \c false.
++
++ This function uses \e ordered \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::testAndSetRelaxed(T *expectedValue, T *newValue, T *&currentValue)
++
++ Atomic test-and-set.
++
++ If the current value of this QAtomicPointer is the \a expectedValue, the
++ test-and-set functions assign the \a newValue to this QAtomicPointer and
++ return \c true. If the values are \e not the same, the functions load the
++ current value of this QAtomicPointer into \a currentValue and return \c false.
++
++ \include qatomic.cpp memory-order-3-arg-relaxed
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::testAndSetAcquire(T *expectedValue, T *newValue, T *&currentValue)
++
++ Atomic test-and-set.
++
++ If the current value of this QAtomicPointer is the \a expectedValue, the
++ test-and-set functions assign the \a newValue to this QAtomicPointer and
++ return \c true. If the values are \e not the same, the functions load the
++ current value of this QAtomicPointer into \a currentValue and return \c false.
++
++ \include qatomic.cpp memory-order-3-arg-acquire
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::testAndSetRelease(T *expectedValue, T *newValue, T *&currentValue)
++
++ Atomic test-and-set.
++
++ If the current value of this QAtomicPointer is the \a expectedValue, the
++ test-and-set functions assign the \a newValue to this QAtomicPointer and
++ return \c true. If the values are \e not the same, the functions load the
++ current value of this QAtomicPointer into \a currentValue and return \c false.
++
++ \include qatomic.cpp memory-order-3-arg-release
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::testAndSetOrdered(T *expectedValue, T *newValue, T *&currentValue)
++
++ Atomic test-and-set.
++
++ If the current value of this QAtomicPointer is the \a expectedValue, the
++ test-and-set functions assign the \a newValue to this QAtomicPointer and
++ return \c true. If the values are \e not the same, the functions load the
++ current value of this QAtomicPointer into \a currentValue and return \c false.
++
++ \include qatomic.cpp memory-order-3-arg-ordered
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::isFetchAndStoreNative()
++
++ Returns \c true if fetch-and-store is implemented using atomic
++ processor instructions, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::isFetchAndStoreWaitFree()
++
++ Returns \c true if atomic fetch-and-store is wait-free, false
++ otherwise.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::fetchAndStoreRelaxed(T *newValue)
++
++ Atomic fetch-and-store.
++
++ Reads the current value of this QAtomicPointer and then assigns it the
++ \a newValue, returning the original value.
++
++ This function uses \e relaxed \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::fetchAndStoreAcquire(T *newValue)
++
++ Atomic fetch-and-store.
++
++ Reads the current value of this QAtomicPointer and then assigns it the
++ \a newValue, returning the original value.
++
++ This function uses \e acquire \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::fetchAndStoreRelease(T *newValue)
++
++ Atomic fetch-and-store.
++
++ Reads the current value of this QAtomicPointer and then assigns it the
++ \a newValue, returning the original value.
++
++ This function uses \e release \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::fetchAndStoreOrdered(T *newValue)
++
++ Atomic fetch-and-store.
++
++ Reads the current value of this QAtomicPointer and then assigns it the
++ \a newValue, returning the original value.
++
++ This function uses \e ordered \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::isFetchAndAddNative()
++
++ Returns \c true if fetch-and-add is implemented using atomic
++ processor instructions, false otherwise.
++ */
++
++ /*!
++ \fn template <typename T> bool QAtomicPointer<T>::isFetchAndAddWaitFree()
++
++ Returns \c true if atomic fetch-and-add is wait-free, false
++ otherwise.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::fetchAndAddRelaxed(qptrdiff valueToAdd)
++
++ Atomic fetch-and-add.
++
++ Reads the current value of this QAtomicPointer and then adds
++ \a valueToAdd to the current value, returning the original value.
++
++ This function uses \e relaxed \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, leaving the compiler and
++ processor to freely reorder memory accesses.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::fetchAndAddAcquire(qptrdiff valueToAdd)
++
++ Atomic fetch-and-add.
++
++ Reads the current value of this QAtomicPointer and then adds
++ \a valueToAdd to the current value, returning the original value.
++
++ This function uses \e acquire \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access following the atomic operation (in program order) may not
++ be re-ordered before the atomic operation.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::fetchAndAddRelease(qptrdiff valueToAdd)
++
++ Atomic fetch-and-add.
++
++ Reads the current value of this QAtomicPointer and then adds
++ \a valueToAdd to the current value, returning the original value.
++
++ This function uses \e release \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before the atomic operation (in program order) may not be
++ re-ordered after the atomic operation.
++ */
++
++ /*!
++ \fn template <typename T> T *QAtomicPointer<T>::fetchAndAddOrdered(qptrdiff valueToAdd)
++
++ Atomic fetch-and-add.
++
++ Reads the current value of this QAtomicPointer and then adds
++ \a valueToAdd to the current value, returning the original value.
++
++ This function uses \e ordered \l {QAtomicPointer#Memory
++ ordering}{memory ordering} semantics, which ensures that memory
++ access before and after the atomic operation (in program order)
++ may not be re-ordered.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined if and only if your processor supports
++ atomic test-and-set on pointers.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined when only certain generations of the
++ processor support atomic test-and-set on pointers. Use the
++ QAtomicPointer::isTestAndSetNative() function to check what your
++ processor supports.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined when the hardware does not support atomic
++ test-and-set on pointers.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
++ \relates QAtomicPointer
++
++ This macro is defined together with
++ Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that
++ the atomic test-and-set on pointers is wait-free.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined if and only if your processor supports
++ atomic fetch-and-store on pointers.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined when only certain generations of the
++ processor support atomic fetch-and-store on pointers. Use the
++ QAtomicPointer::isFetchAndStoreNative() function to check what
++ your processor supports.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined when the hardware does not support atomic
++ fetch-and-store on pointers.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
++ \relates QAtomicPointer
++
++ This macro is defined together with
++ Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE to indicate that
++ the atomic fetch-and-store on pointers is wait-free.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined if and only if your processor supports
++ atomic fetch-and-add on pointers.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined when only certain generations of the
++ processor support atomic fetch-and-add on pointers. Use the
++ QAtomicPointer::isFetchAndAddNative() function to check what your
++ processor supports.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
++ \relates QAtomicPointer
++
++ This macro is defined when the hardware does not support atomic
++ fetch-and-add on pointers.
++ */
++
++ /*!
++ \macro Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
++ \relates QAtomicPointer
++
++ This macro is defined together with
++ Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE to indicate that
++ the atomic fetch-and-add on pointers is wait-free.
++ */
++
++ // static checks
++ #ifndef Q_ATOMIC_INT8_IS_SUPPORTED
++ # error "Q_ATOMIC_INT8_IS_SUPPORTED must be defined"
++ #endif
++ #ifndef Q_ATOMIC_INT16_IS_SUPPORTED
++ # error "Q_ATOMIC_INT16_IS_SUPPORTED must be defined"
++ #endif
++ #ifndef Q_ATOMIC_INT32_IS_SUPPORTED
++ # error "Q_ATOMIC_INT32_IS_SUPPORTED must be defined"
++ #endif
++ #if !defined(Q_ATOMIC_INT64_IS_SUPPORTED) && QT_POINTER_SIZE == 8
++ // 64-bit platform
++ # error "Q_ATOMIC_INT64_IS_SUPPORTED must be defined on a 64-bit platform"
++ #endif
++
++ QT_BEGIN_NAMESPACE
++
++ // The following specializations must always be defined
++ static_assert(sizeof(QAtomicInteger<unsigned>));
++ static_assert(sizeof(QAtomicInteger<long>));
++ static_assert(sizeof(QAtomicInteger<unsigned long>));
++ static_assert(sizeof(QAtomicInteger<quintptr>));
++ static_assert(sizeof(QAtomicInteger<qptrdiff>));
++ static_assert(sizeof(QAtomicInteger<char32_t>));
++
++ static_assert(sizeof(QAtomicInteger<short>));
++ static_assert(sizeof(QAtomicInteger<unsigned short>));
++ static_assert(sizeof(QAtomicInteger<wchar_t>));
++ static_assert(sizeof(QAtomicInteger<char16_t>));
++
++ static_assert(sizeof(QAtomicInteger<char>));
++ static_assert(sizeof(QAtomicInteger<unsigned char>));
++ static_assert(sizeof(QAtomicInteger<signed char>));
++ static_assert(sizeof(QAtomicInteger<bool>));
++
++ #ifdef Q_ATOMIC_INT64_IS_SUPPORTED
++ static_assert(sizeof(QAtomicInteger<qint64>));
++ static_assert(sizeof(QAtomicInteger<quint64>));
++ #endif
++
++ QT_END_NAMESPACE