QtCore.QAtomicInt Class Reference

The QAtomicInt class provides platform-independent atomic operations on integers. More...

Inheritance diagram for QtCore.QAtomicInt:

Collaboration diagram for QtCore.QAtomicInt:

Public Member Functions
	QAtomicInt (QAtomicInt other)
	QAtomicInt (int value=0)
override void	CreateProxy ()
new void	Dispose ()
Public Member Functions inherited from QtCore.QBasicAtomicInt
override bool	Equals (object o)
override int	GetHashCode ()
	QBasicAtomicInt ()
	QBasicAtomicInt (QBasicAtomicInt copy)
new bool	Deref ()
new int	FetchAndAddAcquire (int valueToAdd)
new int	FetchAndAddOrdered (int valueToAdd)
new int	FetchAndAddRelaxed (int valueToAdd)
new int	FetchAndAddRelease (int valueToAdd)
new int	FetchAndStoreAcquire (int newValue)
new int	FetchAndStoreOrdered (int newValue)
new int	FetchAndStoreRelaxed (int newValue)
new int	FetchAndStoreRelease (int newValue)
new bool	Ref ()
new bool	TestAndSetAcquire (int expectedValue, int newValue)
new bool	TestAndSetOrdered (int expectedValue, int newValue)
new bool	TestAndSetRelaxed (int expectedValue, int newValue)
new bool	TestAndSetRelease (int expectedValue, int newValue)
new void	Dispose ()

Protected Member Functions
	QAtomicInt (System.Type dummy)
Protected Member Functions inherited from QtCore.QBasicAtomicInt
	QBasicAtomicInt (System.Type dummy)

Additional Inherited Members
Static Public Member Functions inherited from QtCore.QBasicAtomicInt
static bool	IsFetchAndAddNative ()
static bool	IsFetchAndAddWaitFree ()
static bool	IsFetchAndStoreNative ()
static bool	IsFetchAndStoreWaitFree ()
static bool	IsReferenceCountingNative ()
static bool	IsReferenceCountingWaitFree ()
static bool	IsTestAndSetNative ()
static bool	IsTestAndSetWaitFree ()
static	operator System.Int32 (QBasicAtomicInt arg1)
static bool	operator! (QBasicAtomicInt arg1)
static bool	operator!= (QBasicAtomicInt arg1, int arg2)
static bool	operator== (QBasicAtomicInt arg1, int arg2)
Protected Attributes inherited from QtCore.QBasicAtomicInt
SmokeInvocation	interceptor
Properties inherited from QtCore.QBasicAtomicInt
virtual System.IntPtr	SmokeObject [get, set]

Detailed Description

The QAtomicInt class provides platform-independent atomic operations on integers.

For atomic operations on pointers, see the QAtomicPointer class.

An atomic operation is a complex operation that completes without interruption. The QAtomicInt class provides atomic reference counting, test-and-set, fetch-and-store, and fetch-and-add for integers.

Non-atomic convenience operators

For convenience, QAtomicInt provides integer comparison, cast, and assignment operators. Note that a combination of these operators is not an atomic operation.

The Atomic API

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.

MySharedType &MySharedType::operator=(const MySharedType &other)

{

(void) other.data->atomicInt.ref();

if (!data->atomicInt.deref()) {

// The last reference has been released

delete d;

}

d = other.d;

return *this;

}

Memory ordering

QAtomicInt 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 the QAtomicInt is an expected value, the test-and-set functions assign a new value to the QAtomicInt 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 QAtomicInt and then assign a new value, returning the original value. This operation equates to the following code:

int 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 QAtomicInt and then add the given value to the current value, returning the original value. This operation equates to the following code:

int 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 QAtomicInt is guaranteed to work atomically on all processors. However, since not all processors implement support for every operation provided by QAtomicInt, 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_OPERATION_IS_HOW_NATIVE. OPERATION is one of REFERENCE_COUNTING, 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_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE is defined, neither Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE nor Q_ATOMIC_INT_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_OPERATION_IS_WAIT_FREE in addition to the Q_ATOMIC_INT_OPERATION_IS_ALWAYS_NATIVE.

In cases where an atomic operation is only supported in newer generations of the processor, QAtomicInt 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 QAtomicInt:

Q_ATOMIC_INT_REFERENCE_COUNTING_IS_ALWAYS_NATIVE

Q_ATOMIC_INT_REFERENCE_COUNTING_IS_SOMETIMES_NATIVE

Q_ATOMIC_INT_REFERENCE_COUNTING_IS_NOT_NATIVE

Q_ATOMIC_INT_REFERENCE_COUNTING_IS_WAIT_FREE

Q_ATOMIC_INT_TEST_AND_SET_IS_ALWAYS_NATIVE

Q_ATOMIC_INT_TEST_AND_SET_IS_SOMETIMES_NATIVE

Q_ATOMIC_INT_TEST_AND_SET_IS_NOT_NATIVE

Q_ATOMIC_INT_TEST_AND_SET_IS_WAIT_FREE

Q_ATOMIC_INT_FETCH_AND_STORE_IS_ALWAYS_NATIVE

Q_ATOMIC_INT_FETCH_AND_STORE_IS_SOMETIMES_NATIVE

Q_ATOMIC_INT_FETCH_AND_STORE_IS_NOT_NATIVE

Q_ATOMIC_INT_FETCH_AND_STORE_IS_WAIT_FREE

Q_ATOMIC_INT_FETCH_AND_ADD_IS_ALWAYS_NATIVE

Q_ATOMIC_INT_FETCH_AND_ADD_IS_SOMETIMES_NATIVE

Q_ATOMIC_INT_FETCH_AND_ADD_IS_NOT_NATIVE

Q_ATOMIC_INT_FETCH_AND_ADD_IS_WAIT_FREE

See also QAtomicPointer.

Constructor & Destructor Documentation

QtCore.QAtomicInt.QAtomicInt ( System.Type  dummy )

protected

QtCore.QAtomicInt.QAtomicInt

(

QAtomicInt

other

)

Constructs a copy of other.

QtCore.QAtomicInt.QAtomicInt

(

int

value = 0

)

Constructs a QAtomicInt with the given value.

Member Function Documentation

override void QtCore.QAtomicInt.CreateProxy ( )

virtual

Reimplemented from QtCore.QBasicAtomicInt.

new void QtCore.QAtomicInt.Dispose

(

)