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:
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_OPERATION_IS_HOW_NATIVE. OPERATION is one of 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_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_OPERATION_IS_WAIT_FREE in addition to the Q_ATOMIC_POINTER_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:
See also QAtomicInt.
Member Function Documentation
QAtomicPointer::QAtomicPointer ( T * value = 0 )
Constructs a QAtomicPointer with the given value.
QAtomicPointer::QAtomicPointer ( const QAtomicPointer<T> & other )
Constructs a copy of other.
T * QAtomicPointer::fetchAndAddAcquire ( qptrdiff valueToAdd )
Atomic fetch-and-add.
Reads the current value of this QAtomicPointer 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.
T * QAtomicPointer::fetchAndAddOrdered ( qptrdiff valueToAdd )
Atomic fetch-and-add.
Reads the current value of this QAtomicPointer 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.
T * QAtomicPointer::fetchAndAddRelaxed ( qptrdiff valueToAdd )
Atomic fetch-and-add.
Reads the current value of this QAtomicPointer 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.
T * QAtomicPointer::fetchAndAddRelease ( qptrdiff valueToAdd )
Atomic fetch-and-add.
Reads the current value of this QAtomicPointer 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.
T * QAtomicPointer::fetchAndStoreAcquire ( T * newValue )
Atomic fetch-and-store.
Reads the current value of this QAtomicPointer 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 * QAtomicPointer::fetchAndStoreOrdered ( T * newValue )
Atomic fetch-and-store.
Reads the current value of this QAtomicPointer 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 * QAtomicPointer::fetchAndStoreRelaxed ( T * newValue )
Atomic fetch-and-store.
Reads the current value of this QAtomicPointer 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 * QAtomicPointer::fetchAndStoreRelease ( T * newValue )
Atomic fetch-and-store.
Reads the current value of this QAtomicPointer 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.
bool QAtomicPointer::isFetchAndAddNative () [static]
Returns true if fetch-and-add is implemented using atomic processor instructions, false otherwise.
bool QAtomicPointer::isFetchAndAddWaitFree () [static]
Returns true if atomic fetch-and-add is wait-free, false otherwise.
bool QAtomicPointer::isFetchAndStoreNative () [static]
Returns true if fetch-and-store is implemented using atomic processor instructions, false otherwise.
bool QAtomicPointer::isFetchAndStoreWaitFree () [static]
Returns true if atomic fetch-and-store is wait-free, false otherwise.
bool QAtomicPointer::isTestAndSetNative () [static]
Returns true if test-and-set is implemented using atomic processor instructions, false otherwise.
bool QAtomicPointer::isTestAndSetWaitFree () [static]
Returns true if atomic test-and-set is wait-free, false otherwise.
bool QAtomicPointer::testAndSetAcquire ( T * expectedValue, T * newValue )
Atomic test-and-set.
If the current value of this QAtomicPointer is the expectedValue, the test-and-set functions assign the newValue to this QAtomicPointer 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 QAtomicPointer::testAndSetOrdered ( T * expectedValue, T * newValue )
Atomic test-and-set.
If the current value of this QAtomicPointer is the expectedValue, the test-and-set functions assign the newValue to this QAtomicPointer 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 QAtomicPointer::testAndSetRelaxed ( T * expectedValue, T * newValue )
Atomic test-and-set.
If the current value of this QAtomicPointer is the expectedValue, the test-and-set functions assign the newValue to this QAtomicPointer 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 QAtomicPointer::testAndSetRelease ( T * expectedValue, T * newValue )
Atomic test-and-set.
If the current value of this QAtomicPointer is the expectedValue, the test-and-set functions assign the newValue to this QAtomicPointer 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.
QAtomicPointer::operator T * () const
Returns the current pointer value stored by this QAtomicPointer object.
bool QAtomicPointer::operator! () const
Returns true is the current value of this QAtomicPointer is zero; otherwise returns false.
bool QAtomicPointer::operator!= ( T * value ) const
Returns true if the value of this QAtomicPointer is not equal to value; otherwise returns false.
T * QAtomicPointer::operator-> () const
QAtomicPointer<T> & QAtomicPointer::operator= ( T * value )
Assigns the value to this QAtomicPointer and returns a reference to this QAtomicPointer.
QAtomicPointer<T> & QAtomicPointer::operator= ( const QAtomicPointer<T> & other )
This is an overloaded member function, provided for convenience.
Assigns other to this QAtomicPointer and returns a reference to this QAtomicPointer.
bool QAtomicPointer::operator== ( T * value ) const
Returns true if the value is equal to the value in this QAtomicPointer; otherwise returns false.
Macro Documentation
Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
This macro is defined if and only if your processor supports atomic fetch-and-add on pointers.
Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
This macro is defined when the hardware does not support atomic fetch-and-add on pointers.
Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
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.
Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE
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.
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
This macro is defined if and only if your processor supports atomic fetch-and-store on pointers.
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
This macro is defined when the hardware does not support atomic fetch-and-store on pointers.
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
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.
Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
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.
Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
This macro is defined if and only if your processor supports atomic test-and-set on pointers.
Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
This macro is defined when the hardware does not support atomic test-and-set on pointers.
Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
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.
Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
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.