vtkm::exec::AtomicArrayExecutionObject< T > Class Template Reference

#include <AtomicArrayExecutionObject.h>

Classes
struct	HasPointerAccess

Public Types
using	ValueType = T

Public Member Functions
	AtomicArrayExecutionObject ()=default
	AtomicArrayExecutionObject (vtkm::cont::ArrayHandle< T > handle, vtkm::cont::DeviceAdapterId device, vtkm::cont::Token &token)
vtkm::Id	GetNumberOfValues () const
ValueType	Get (vtkm::Id index, vtkm::MemoryOrder order=vtkm::MemoryOrder::Acquire) const
	Perform an atomic load of the indexed element with acquire memory ordering. More...
ValueType	Add (vtkm::Id index, const ValueType &value, vtkm::MemoryOrder order=vtkm::MemoryOrder::SequentiallyConsistent) const
	Peform an atomic addition with sequentially consistent memory ordering. More...
void	Set (vtkm::Id index, const ValueType &value, vtkm::MemoryOrder order=vtkm::MemoryOrder::Release) const
	Peform an atomic store to memory while enforcing, at minimum, "release" memory ordering. More...
bool	CompareExchange (vtkm::Id index, ValueType *oldValue, const ValueType &newValue, vtkm::MemoryOrder order=vtkm::MemoryOrder::SequentiallyConsistent) const
	Perform an atomic compare and exchange operation with sequentially consistent memory ordering. More...

Private Attributes
ValueType *	Data { nullptr }
vtkm::Id	NumberOfValues { 0 }

Member Typedef Documentation

ValueType

template<typename T >

using vtkm::exec::AtomicArrayExecutionObject< T >::ValueType = T

Constructor & Destructor Documentation

AtomicArrayExecutionObject() [1/2]

template<typename T >

vtkm::exec::AtomicArrayExecutionObject< T >::AtomicArrayExecutionObject ( )

default

AtomicArrayExecutionObject() [2/2]

template<typename T >

vtkm::exec::AtomicArrayExecutionObject< T >::AtomicArrayExecutionObject ( vtkm::cont::ArrayHandle< T >  handle, vtkm::cont::DeviceAdapterId  device, vtkm::cont::Token &  token  )

inline

Member Function Documentation

Add()

template<typename T >

ValueType vtkm::exec::AtomicArrayExecutionObject< T >::Add ( vtkm::Id  index, const ValueType &  value, vtkm::MemoryOrder  order = vtkm::MemoryOrder::SequentiallyConsistent  ) const

inline

Peform an atomic addition with sequentially consistent memory ordering.

Parameters

index	The index of the array element that will be added to.
value	The addend of the atomic add operation.
order	The memory ordering to use for the add operation.

Returns

The original value of the element at index (before addition).

Warning

Overflow behavior from this operation is undefined.

CompareExchange()

template<typename T >

bool vtkm::exec::AtomicArrayExecutionObject< T >::CompareExchange ( vtkm::Id  index, ValueType *  oldValue, const ValueType &  newValue, vtkm::MemoryOrder  order = vtkm::MemoryOrder::SequentiallyConsistent  ) const

inline

Perform an atomic compare and exchange operation with sequentially consistent memory ordering.

Parameters

index	The index of the array element that will be atomically modified.
oldValue	A pointer to the expected value of the indexed element.
newValue	The value to replace the indexed element with.
order	The memory ordering to use for the compare and exchange operation.

Returns

If the operation is successful, true is returned. Otherwise, oldValue is replaced with the current value of the indexed element, the element is not modified, and false is returned. In either case, oldValue becomes the value that was originally in the indexed element.

This operation is typically used in a loop. For example usage, an atomic multiplication may be implemented using compare-exchange as follows:

AtomicArrayExecutionObject<vtkm::Int32> atomicArray = ...;
 
// Compare-exchange multiplication:
vtkm::Int32 current = atomicArray.Get(idx); // Load the current value at idx
vtkm::Int32 newVal;
do {
  newVal = current * multFactor; // the actual multiplication
} while (!atomicArray.CompareExchange(idx, &current, newVal));

The while condition here updates newVal what the proper multiplication is given the expected current value. It then compares this to the value in the array. If the values match, the operation was successful and the loop exits. If the values do not match, the value at idx was changed by another thread since the initial Get, and the compare-exchange operation failed – the target element was not modified by the compare-exchange call. If this happens, the loop body re-executes using the new value of current and tries again until it succeeds.

Note that for demonstration purposes, the previous code is unnecessarily verbose. We can express the same atomic operation more succinctly with just two lines where newVal is just computed in place.

vtkm::Int32 current = atomicArray.Get(idx); // Load the current value at idx
while (!atomicArray.CompareExchange(idx, &current, current * multFactor));

Get()

template<typename T >

ValueType vtkm::exec::AtomicArrayExecutionObject< T >::Get ( vtkm::Id  index, vtkm::MemoryOrder  order = vtkm::MemoryOrder::Acquire  ) const

inline

Perform an atomic load of the indexed element with acquire memory ordering.

Parameters

index	The index of the element to load.
order	The memory ordering to use for the load operation.

Returns

The value of the atomic array at index.

GetNumberOfValues()

template<typename T >

vtkm::Id vtkm::exec::AtomicArrayExecutionObject< T >::GetNumberOfValues ( ) const

inline

Set()

template<typename T >

void vtkm::exec::AtomicArrayExecutionObject< T >::Set ( vtkm::Id  index, const ValueType &  value, vtkm::MemoryOrder  order = vtkm::MemoryOrder::Release  ) const

inline

Peform an atomic store to memory while enforcing, at minimum, "release" memory ordering.

Parameters

index	The index of the array element that will be added to.
value	The value to write for the atomic store operation.
order	The memory ordering to use for the store operation.

Warning

Using something like:

Set(index, Get(index)+N)

Should not be done as it is not thread safe, instead you should use the provided Add method instead.

Member Data Documentation

Data

template<typename T >

ValueType* vtkm::exec::AtomicArrayExecutionObject< T >::Data { nullptr }

private

NumberOfValues

template<typename T >

vtkm::Id vtkm::exec::AtomicArrayExecutionObject< T >::NumberOfValues { 0 }

private

---

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

• AtomicArrayExecutionObject.h