Qt 4.8
Public Functions | Static Public Functions | List of all members
QAtomicPointer< T > Class Template Reference

The QAtomicPointer class is a template class that provides platform-independent atomic operations on pointers. More...

#include <qsimplecodec_p.h>

Inheritance diagram for QAtomicPointer< T >:
QBasicAtomicPointer< T >

Public Functions

T * fetchAndAddAcquire (qptrdiff valueToAdd)
 Atomic fetch-and-add. More...
 
T * fetchAndAddOrdered (qptrdiff valueToAdd)
 Atomic fetch-and-add. More...
 
T * fetchAndAddRelaxed (qptrdiff valueToAdd)
 Atomic fetch-and-add. More...
 
T * fetchAndAddRelease (qptrdiff valueToAdd)
 Atomic fetch-and-add. More...
 
T * fetchAndStoreAcquire (T *newValue)
 Atomic fetch-and-store. More...
 
T * fetchAndStoreOrdered (T *newValue)
 Atomic fetch-and-store. More...
 
T * fetchAndStoreRelaxed (T *newValue)
 Atomic fetch-and-store. More...
 
T * fetchAndStoreRelease (T *newValue)
 Atomic fetch-and-store. More...
 
 operator T* () const
 Returns the current pointer value stored by this QAtomicPointer object. More...
 
bool operator! () const
 Returns true is the current value of this QAtomicPointer is zero; otherwise returns false. More...
 
bool operator!= (T *value) const
 Returns true if the value of this QAtomicPointer is not equal to value; otherwise returns false. More...
 
T * operator-> () const
 
QAtomicPointer< T > & operator= (T *value)
 Assigns the value to this QAtomicPointer and returns a reference to this QAtomicPointer. More...
 
QAtomicPointer< T > & operator= (const QAtomicPointer< T > &other)
 Assigns other to this QAtomicPointer and returns a reference to this QAtomicPointer. More...
 
bool operator== (T *value) const
 Returns true if the value is equal to the value in this QAtomicPointer; otherwise returns false. More...
 
 QAtomicPointer (T *value=0)
 Constructs a QAtomicPointer with the given value. More...
 
 QAtomicPointer (const QAtomicPointer< T > &other)
 Constructs a copy of other. More...
 
bool testAndSetAcquire (T *expectedValue, T *newValue)
 Atomic test-and-set. More...
 
bool testAndSetOrdered (T *expectedValue, T *newValue)
 Atomic test-and-set. More...
 
bool testAndSetRelaxed (T *expectedValue, T *newValue)
 Atomic test-and-set. More...
 
bool testAndSetRelease (T *expectedValue, T *newValue)
 Atomic test-and-set. More...
 
- Public Functions inherited from QBasicAtomicPointer< T >
T * fetchAndAddAcquire (qptrdiff valueToAdd)
 
T * fetchAndAddOrdered (qptrdiff valueToAdd)
 
T * fetchAndAddRelaxed (qptrdiff valueToAdd)
 
T * fetchAndAddRelease (qptrdiff valueToAdd)
 
T * fetchAndStoreAcquire (T *newValue)
 
T * fetchAndStoreOrdered (T *newValue)
 
T * fetchAndStoreRelaxed (T *newValue)
 
T * fetchAndStoreRelease (T *newValue)
 
 operator T* () const
 
bool operator! () const
 
bool operator!= (T *value) const
 
T * operator-> () const
 
QBasicAtomicPointer< T > & operator= (T *value)
 
bool operator== (T *value) const
 
bool testAndSetAcquire (T *expectedValue, T *newValue)
 
bool testAndSetOrdered (T *expectedValue, T *newValue)
 
bool testAndSetRelaxed (T *expectedValue, T *newValue)
 
bool testAndSetRelease (T *expectedValue, T *newValue)
 

Static Public Functions

static bool isFetchAndAddNative ()
 Returns true if fetch-and-add is implemented using atomic processor instructions, false otherwise. More...
 
static bool isFetchAndAddWaitFree ()
 Returns true if atomic fetch-and-add is wait-free, false otherwise. More...
 
static bool isFetchAndStoreNative ()
 Returns true if fetch-and-store is implemented using atomic processor instructions, false otherwise. More...
 
static bool isFetchAndStoreWaitFree ()
 Returns true if atomic fetch-and-store is wait-free, false otherwise. More...
 
static bool isTestAndSetNative ()
 Returns true if test-and-set is implemented using atomic processor instructions, false otherwise. More...
 
static bool isTestAndSetWaitFree ()
 Returns true if atomic test-and-set is wait-free, false otherwise. More...
 
- Static Public Functions inherited from QBasicAtomicPointer< T >
static bool isFetchAndAddNative ()
 
static bool isFetchAndAddWaitFree ()
 
static bool isFetchAndStoreNative ()
 
static bool isFetchAndStoreWaitFree ()
 
static bool isTestAndSetNative ()
 
static bool isTestAndSetWaitFree ()
 

Additional Inherited Members

- Public Variables inherited from QBasicAtomicPointer< T >
T *volatile _q_value
 

Detailed Description

template<typename T>
class QAtomicPointer< T >

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

Since
4.4

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 operators

For convenience, QAtomicPointer provides pointer comparison, cast, dereference, and assignment operators. Note that these operators are not 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.

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 not the same, these functions do nothing and return false. This operation equates to the following code:

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

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

Fetch-and-store

The atomic fetch-and-store functions read the current value of the 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-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:

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 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

Definition at line 62 of file qsimplecodec_p.h.

Constructors and Destructors

◆ QAtomicPointer() [1/2]

template<typename T>
QAtomicPointer< T >::QAtomicPointer ( T *  value = 0)
inline

Constructs a QAtomicPointer with the given value.

Definition at line 128 of file qatomic.h.

129  {
130 #ifdef QT_ARCH_PARISC
131  this->_q_lock[0] = this->_q_lock[1] = this->_q_lock[2] = this->_q_lock[3] = -1;
132 #endif
134  }

◆ QAtomicPointer() [2/2]

template<typename T>
QAtomicPointer< T >::QAtomicPointer ( const QAtomicPointer< T > &  other)
inline

Constructs a copy of other.

Definition at line 135 of file qatomic.h.

136  {
137 #ifdef QT_ARCH_PARISC
138  this->_q_lock[0] = this->_q_lock[1] = this->_q_lock[2] = this->_q_lock[3] = -1;
139 #endif
141  }
T *volatile _q_value
Definition: qbasicatomic.h:148

Functions

◆ fetchAndAddAcquire()

template<typename T>
T * QAtomicPointer< T >::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.

◆ fetchAndAddOrdered()

template<typename T>
T * QAtomicPointer< T >::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.

◆ fetchAndAddRelaxed()

template<typename T>
T * QAtomicPointer< T >::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.

◆ fetchAndAddRelease()

template<typename T>
T * QAtomicPointer< T >::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.

◆ fetchAndStoreAcquire()

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 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.

◆ fetchAndStoreOrdered()

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 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.

◆ fetchAndStoreRelaxed()

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 newValue, returning the original value.

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

◆ fetchAndStoreRelease()

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 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.

◆ isFetchAndAddNative()

template<typename T>
bool QAtomicPointer< T >::isFetchAndAddNative ( )
static

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

◆ isFetchAndAddWaitFree()

template<typename T>
bool QAtomicPointer< T >::isFetchAndAddWaitFree ( )
static

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

◆ isFetchAndStoreNative()

template<typename T>
bool QAtomicPointer< T >::isFetchAndStoreNative ( )
static

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

◆ isFetchAndStoreWaitFree()

template<typename T>
bool QAtomicPointer< T >::isFetchAndStoreWaitFree ( )
static

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

◆ isTestAndSetNative()

template<typename T>
bool QAtomicPointer< T >::isTestAndSetNative ( )
static

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

◆ isTestAndSetWaitFree()

template<typename T>
bool QAtomicPointer< T >::isTestAndSetWaitFree ( )
static

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

◆ operator T*()

template<typename T>
QAtomicPointer< T >::operator T* ( ) const

Returns the current pointer value stored by this QAtomicPointer object.

◆ operator!()

template<typename T>
bool QAtomicPointer< T >::operator! ( ) const

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

◆ operator!=()

template<typename T>
bool QAtomicPointer< T >::operator!= ( T *  value) const

Returns true if the value of this QAtomicPointer is not equal to value; otherwise returns false.

◆ operator->()

template<typename T>
T * QAtomicPointer< T >::operator-> ( ) const

◆ operator=() [1/2]

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

Assigns the value to this QAtomicPointer and returns a reference to this QAtomicPointer.

Definition at line 143 of file qatomic.h.

144  {
145  (void) QBasicAtomicPointer<T>::operator=(value);
146  return *this;
147  }

◆ operator=() [2/2]

template<typename T>
QAtomicPointer< T > & QAtomicPointer< T >::operator= ( const QAtomicPointer< T > &  other)
inline

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

Definition at line 149 of file qatomic.h.

150  {
151  (void) QBasicAtomicPointer<T>::operator=(other);
152  return *this;
153  }

◆ operator==()

template<typename T>
bool QAtomicPointer< T >::operator== ( T *  value) const

Returns true if the value is equal to the value in this QAtomicPointer; otherwise returns false.

◆ testAndSetAcquire()

template<typename T>
bool QAtomicPointer< T >::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.

◆ testAndSetOrdered()

template<typename T>
bool QAtomicPointer< T >::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.

Referenced by QSimpleTextCodec::convertFromUnicode().

◆ testAndSetRelaxed()

template<typename T>
bool QAtomicPointer< T >::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.

◆ testAndSetRelease()

template<typename T>
bool QAtomicPointer< T >::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.


The documentation for this class was generated from the following files: