              
QAtomicPointer Class ReferenceThe QAtomicPointer class is a template class that provides platform-independent atomic operations on pointers. More... #include <QAtomicPointer>This class was introduced in Qt 4.4. Public Functions
Static Public Members
MacrosDetailed DescriptionThe QAtomicPointer class is a template class that provides platform-independent atomic operations on pointers. For atomic operations on integers, see the QAtomicInt class. An 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. Non-atomic convenience operatorsFor convenience, QAtomicPointer provides pointer comparison, cast, dereference, and assignment operators. Note that these operators are not atomic. The Atomic APIMemory orderingQAtomicPointer 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.
Test-and-setIf 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 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-storeThe 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: T *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-addThe 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: T *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 APIProviding 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
|
