4.8. Memory Layout of Array Handles

Chapter 3.2 (Basic Array Handles) describes the basics of the vtkm::cont::ArrayHandle class, which is the interface to the arrays of data that VTK‑m operates on. Recall that vtkm::cont::ArrayHandle is a templated class with two template parameters. The first template argument is the type of each item in the array. The second parameter, which is optional, determines how the array is stored in memory. This can be used in a variety of different ways, but its primary purpose is to provide a strategy for laying the data out in memory. This chapter documents the ways in which VTK‑m can store and access arrays of data in different layouts.

4.8.1. Basic Memory Layout

If the second storage template parameter of vtkm::cont::ArrayHandle is not specified, it defaults to the basic memory layout. This is roughly synonymous with a wrapper around a standard C array, much like std::vector. In fact, Section 3.2.1 (Creating Array Handles) provides examples of wrapping a default vtkm::cont::ArrayHandle around either a basic C array or a std::vector.

VTK‑m provides vtkm::cont::ArrayHandleBasic as a convenience class for working with basic array handles. vtkm::cont::ArrayHandleBasic is a simple subclass of vtkm::cont::ArrayHandle with the default storage in the second template argument (which is vtkm::cont::StorageTagBasic). vtkm::cont::ArrayHandleBasic and its superclass can be used more or less interchangeably.

template<typename T> class ArrayHandleBasic : public vtkm::cont::ArrayHandle<T, vtkm::cont::StorageTagBasic>

Basic array storage for an array handle.

This array handle references a standard C array. It provides a level of safety and management across devices. This is the default used when no storage is specified. Using this subclass allows access to the underlying raw array.

Public Functions

inline const T *GetReadPointer() const

Gets raw access to the ArrayHandle’s data.

Note that the returned array may become invalidated by other operations on the ArryHandle.

inline const T *GetReadPointer(vtkm::cont::Token &token) const

Gets raw access to the ArrayHandle’s data.

Parameters:: token – When a vtkm::cont::Token is provided, the array is locked from being used by any write operations until the token goes out of scope.

inline T *GetWritePointer() const

Gets raw write access to the ArrayHandle’s data.

Note that the returned array may become invalidated by other operations on the ArryHandle.

inline T *GetWritePointer(vtkm::cont::Token &token) const

Gets raw write access to the ArrayHandle’s data.

Parameters:: token – When a vtkm::cont::Token is provided, the array is locked from being used by any read or write operations until the token goes out of scope.

inline const T *GetReadPointer(vtkm::cont::DeviceAdapterId device) const

Gets raw access to the ArrayHandle’s data on a particular device.

Note that the returned array may become invalidated by other operations on the ArryHandle.

Parameters:: device – The device ID or device tag specifying on which device the array will be valid on.

inline const T *GetReadPointer(vtkm::cont::DeviceAdapterId device, vtkm::cont::Token &token) const

Gets raw access to the ArrayHandle’s data.

Parameters:

device – The device ID or device tag specifying on which device the array will be valid on.
token – When a vtkm::cont::Token is provided, the array is locked from being used by any write operations until the token goes out of scope.

inline T *GetWritePointer(vtkm::cont::DeviceAdapterId device) const

Gets raw write access to the ArrayHandle’s data.

Note that the returned array may become invalidated by other operations on the ArryHandle.

Parameters:: device – The device ID or device tag specifying on which device the array will be valid on.

inline T *GetWritePointer(vtkm::cont::DeviceAdapterId device, vtkm::cont::Token &token) const

Gets raw write access to the ArrayHandle’s data.

Parameters:

device – The device ID or device tag specifying on which device the array will be valid on.
token – When a vtkm::cont::Token is provided, the array is locked from being used by any read or write operations until the token goes out of scope.

Because a vtkm::cont::ArrayHandleBasic represents arrays as a standard C array, it is possible to get a pointer to this array using either vtkm::cont::ArrayHandleBasic::GetReadPointer() or vtkm::cont::ArrayHandleBasic::GetWritePointer().

Example 4.72 Getting a standard C array from a basic array handle.

void LegacyFunction(const int* data);

void UseArrayWithLegacy(const vtkm::cont::ArrayHandle<vtkm::Int32> array)
{
  vtkm::cont::ArrayHandleBasic<vtkm::Int32> basicArray = array;
  vtkm::cont::Token token; // Token prevents array from changing while in scope.
  const int* cArray = basicArray.GetReadPointer(token);
  LegacyFunction(cArray);
  // When function returns, token goes out of scope and array can be modified.
}

Did You Know?

When you get an array pointer this way, the vtkm::cont::ArrayHandle still has a reference to it. If using multiple threads, you can use a vtkm::cont::Token object to lock the array. When the token is used to get a pointer, it will lock the array as long as the token exists. Example 4.72 demonstrates using a vtkm::cont::Token.

4.8.2. Structure of Arrays

The basic vtkm::cont::ArrayHandle stores vtkm::Vec objects in sequence. In this sense, a basic array is an Array of Structures (AOS). Another approach is to store each component of the structure (i.e., the vtkm::Vec) in a separate array. This is known as a Structure of Arrays (SOA). There are advantages to this approach including potentially better cache performance and the ability to combine arrays already represented as separate components without copying them. Arrays of this nature are represented with a vtkm::cont::ArrayHandleSOA, which is a subclass of vtkm::cont::StorageTagSOA.

template<typename T> class ArrayHandleSOA : public vtkm::cont::ArrayHandle<T, vtkm::cont::StorageTagSOA>

An ArrayHandle that for Vecs stores each component in a separate physical array.

ArrayHandleSOA behaves like a regular ArrayHandle (with a basic storage) except that if you specify a ValueType of a Vec or a Vec-like, it will actually store each component in a separate physical array. When data are retrieved from the array, they are reconstructed into Vec objects as expected.

The intention of this array type is to help cover the most common ways data is lain out in memory. Typically, arrays of data are either an “array of structures” like the basic storage where you have a single array of structures (like Vec) or a “structure of arrays” where you have an array of a basic type (like float) for each component of the data being represented. The ArrayHandleSOA makes it easy to cover this second case without creating special types.

ArrayHandleSOA can be constructed from a collection of ArrayHandle with basic storage. This allows you to construct Vec arrays from components without deep copies.

Public Functions

inline ArrayHandleSOA(const std::array<ComponentArrayType, NUM_COMPONENTS> &componentArrays)