Contents

• Public Functions
• Static Public Members
• Macros
• Detailed Description
• Non-atomic convenience operators
• The Atomic API
• Feature Tests for the Atomic API

Detailed Description

TheQAtomicPointer class is a template class that provides platform-independent atomic operations on pointers.

For atomic operations on integers, see theQAtomicInt class.

Anatomic operation is a complex operation that completes without interruption. TheQAtomicPointer class provides atomic test-and-set, fetch-and-store, and fetch-and-add for pointers.

Non-atomic convenience operators

For convenience,QAtomicPointer provides pointer comparison, cast, dereference, and assignment operators. Note that these operators arenot atomic.

The Atomic API

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.

• 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 theQAtomicPointer is an expected value, the test-and-set functions assign a new value to theQAtomicPointer and return true. If values arenot the same, these functions do nothing and return false. This operation equates to the following code:

if (currentValue== expectedValue) {    currentValue= newValue;returntrue;}returnfalse;

There are 4 test-and-set functions:testAndSetRelaxed(),testAndSetAcquire(),testAndSetRelease(), andtestAndSetOrdered(). 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 theQAtomicPointer 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(), andfetchAndStoreOrdered(). 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 theQAtomicPointer 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(), andfetchAndAddOrdered(). 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 byQAtomicPointer is guaranteed to work atomically on all processors. However, since not all processors implement support for every operation provided byQAtomicPointer, 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 ofTEST_AND_SET,FETCH_AND_STORE, orFETCH_AND_ADD, andHOW is one of ALWAYS, SOMETIMES, or NOT. There will always be exactly one defined macro per operation. For example, ifQ_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE is defined, neitherQ_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE norQ_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 theisTestAndSetNative(),isFetchAndStoreNative(), andisFetchAndAddNative() functions. Wait-free implementations can be detected using theisTestAndSetWaitFree(),isFetchAndStoreWaitFree(), andisFetchAndAddWaitFree() functions.

Below is a complete list of all feature macros forQAtomicPointer:

• Q_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE
• Q_ATOMIC_POINTER_TEST_AND_SET_IS_SOMETIMES_NATIVE
• Q_ATOMIC_POINTER_TEST_AND_SET_IS_NOT_NATIVE
• Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE
• Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_ALWAYS_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_SOMETIMES_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_NOT_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE
• Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_ALWAYS_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_SOMETIMES_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_NOT_NATIVE
• Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

Member Function Documentation

QAtomicPointer::QAtomicPointer(T * value = 0)

Constructs aQAtomicPointer with the givenvalue.

QAtomicPointer::QAtomicPointer(constQAtomicPointer<T> & other)

Constructs a copy ofother.

T * QAtomicPointer::fetchAndAddAcquire(qptrdiff valueToAdd)

Atomic fetch-and-add.

Reads the current value of thisQAtomicPointer and then addsvalueToAdd to the current value, returning the original value.

This function usesacquirememory 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 thisQAtomicPointer and then addsvalueToAdd to the current value, returning the original value.

This function usesorderedmemory 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 thisQAtomicPointer and then addsvalueToAdd to the current value, returning the original value.

This function usesrelaxedmemory 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 thisQAtomicPointer and then addsvalueToAdd to the current value, returning the original value.

This function usesreleasememory 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 thisQAtomicPointer and then assigns it thenewValue, returning the original value.

This function usesacquirememory 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 thisQAtomicPointer and then assigns it thenewValue, returning the original value.

This function usesorderedmemory 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 thisQAtomicPointer and then assigns it thenewValue, returning the original value.

This function usesrelaxedmemory 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 thisQAtomicPointer and then assigns it thenewValue, returning the original value.

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

[static]bool QAtomicPointer::isFetchAndAddNative()

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

[static]bool QAtomicPointer::isFetchAndAddWaitFree()

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

[static]bool QAtomicPointer::isFetchAndStoreNative()

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

[static]bool QAtomicPointer::isFetchAndStoreWaitFree()

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

[static]bool QAtomicPointer::isTestAndSetNative()

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

[static]bool QAtomicPointer::isTestAndSetWaitFree()

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 thisQAtomicPointer is theexpectedValue, the test-and-set functions assign thenewValue to thisQAtomicPointer and return true. If the values arenot the same, this function does nothing and returns false.

This function usesacquirememory 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 thisQAtomicPointer is theexpectedValue, the test-and-set functions assign thenewValue to thisQAtomicPointer and return true. If the values arenot the same, this function does nothing and returns false.

This function usesorderedmemory 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 thisQAtomicPointer is theexpectedValue, the test-and-set functions assign thenewValue to thisQAtomicPointer and return true. If the values arenot the same, this function does nothing and returns false.

This function usesrelaxedmemory 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 thisQAtomicPointer is theexpectedValue, the test-and-set functions assign thenewValue to thisQAtomicPointer and return true. If the values arenot the same, this function does nothing and returns false.

This function usesreleasememory 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 thisQAtomicPointer object.

bool QAtomicPointer::operator!() const

Returns true is the current value of thisQAtomicPointer is zero; otherwise returns false.

bool QAtomicPointer::operator!=(T * value) const

Returns true if the value of thisQAtomicPointer is not equal tovalue; otherwise returns false.

T * QAtomicPointer::operator->() const

QAtomicPointer<T> & QAtomicPointer::operator=(T * value)

Assigns thevalue to thisQAtomicPointer and returns a reference to thisQAtomicPointer.

QAtomicPointer<T> & QAtomicPointer::operator=(constQAtomicPointer<T> & other)

Assignsother to thisQAtomicPointer and returns a reference to thisQAtomicPointer.

bool QAtomicPointer::operator==(T * value) const

Returns true if thevalue is equal to the value in thisQAtomicPointer; 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 theQAtomicPointer::isFetchAndAddNative() function to check what your processor supports.

Q_ATOMIC_POINTER_FETCH_AND_ADD_IS_WAIT_FREE

This macro is defined together withQ_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 theQAtomicPointer::isFetchAndStoreNative() function to check what your processor supports.

Q_ATOMIC_POINTER_FETCH_AND_STORE_IS_WAIT_FREE

This macro is defined together withQ_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 theQAtomicPointer::isTestAndSetNative() function to check what your processor supports.

Q_ATOMIC_POINTER_TEST_AND_SET_IS_WAIT_FREE

This macro is defined together withQ_ATOMIC_POINTER_TEST_AND_SET_IS_ALWAYS_NATIVE to indicate that the atomic test-and-set on pointers is wait-free.