VTK-m  1.4
Classes | Public Types | Public Member Functions | Public Attributes | Private Types | List of all members
vtkm::cont::ArrayHandle< T, StorageTag_ > Class Template Reference

Manages an array-worth of data. More...

#include <ArrayHandle.h>

Inheritance diagram for vtkm::cont::ArrayHandle< T, StorageTag_ >:
Inheritance graph
[legend]
Collaboration diagram for vtkm::cont::ArrayHandle< T, StorageTag_ >:
Collaboration graph
[legend]

Classes

struct  ExecutionTypes
 
struct  InternalStruct
 

Public Types

using StorageType = vtkm::cont::internal::Storage< T, StorageTag_ >
 
using ValueType = T
 
using StorageTag = StorageTag_
 
using PortalControl = typename StorageType::PortalType
 
using PortalConstControl = typename StorageType::PortalConstType
 

Public Member Functions

VTKM_CONT ArrayHandle ()
 Constructs an empty ArrayHandle. More...
 
 ArrayHandle (const vtkm::cont::ArrayHandle< ValueType, StorageTag > &src)
 Copy constructor. More...
 
 ArrayHandle (vtkm::cont::ArrayHandle< ValueType, StorageTag > &&src) noexcept
 Move constructor. More...
 
 ArrayHandle (const StorageType &storage)
 Special constructor for subclass specializations that need to set the initial state of the control array. More...
 
 ArrayHandle (StorageType &&storage) noexcept
 Special constructor for subclass specializations that need to set the initial state of the control array. More...
 
 ~ArrayHandle ()
 Destructs an empty ArrayHandle. More...
 
VTKM_CONT vtkm::cont::ArrayHandle< ValueType, StorageTag > & operator= (const vtkm::cont::ArrayHandle< ValueType, StorageTag > &src)
 Copies an ArrayHandle. More...
 
VTKM_CONT vtkm::cont::ArrayHandle< ValueType, StorageTag > & operator= (vtkm::cont::ArrayHandle< ValueType, StorageTag > &&src) noexcept
 Move and Assignment of an ArrayHandle. More...
 
VTKM_CONT bool operator== (const ArrayHandle< ValueType, StorageTag > &rhs) const
 Like a pointer, two ArrayHandles are considered equal if they point to the same location in memory. More...
 
VTKM_CONT bool operator!= (const ArrayHandle< ValueType, StorageTag > &rhs) const
 
template<typename VT , typename ST >
VTKM_CONT bool operator== (const ArrayHandle< VT, ST > &) const
 
template<typename VT , typename ST >
VTKM_CONT bool operator!= (const ArrayHandle< VT, ST > &) const
 
VTKM_CONT StorageTypeGetStorage ()
 Get the storage. More...
 
VTKM_CONT const StorageTypeGetStorage () const
 Get the storage. More...
 
VTKM_CONT PortalControl GetPortalControl ()
 Get the array portal of the control array. More...
 
VTKM_CONT PortalConstControl GetPortalConstControl () const
 Get the array portal of the control array. More...
 
VTKM_CONT vtkm::Id GetNumberOfValues () const
 Returns the number of entries in the array. More...
 
VTKM_CONT void Allocate (vtkm::Id numberOfValues)
 Allocates an array large enough to hold the given number of values. More...
 
void Shrink (vtkm::Id numberOfValues)
 Reduces the size of the array without changing its values. More...
 
VTKM_CONT void ReleaseResourcesExecution ()
 Releases any resources being used in the execution environment (that are not being shared by the control environment). More...
 
VTKM_CONT void ReleaseResources ()
 Releases all resources in both the control and execution environments. More...
 
template<typename DeviceAdapterTag >
VTKM_CONT ExecutionTypes< DeviceAdapterTag >::PortalConst PrepareForInput (DeviceAdapterTag) const
 Prepares this array to be used as an input to an operation in the execution environment. More...
 
template<typename DeviceAdapterTag >
VTKM_CONT ExecutionTypes< DeviceAdapterTag >::Portal PrepareForOutput (vtkm::Id numberOfValues, DeviceAdapterTag)
 Prepares (allocates) this array to be used as an output from an operation in the execution environment. More...
 
template<typename DeviceAdapterTag >
VTKM_CONT ExecutionTypes< DeviceAdapterTag >::Portal PrepareForInPlace (DeviceAdapterTag)
 Prepares this array to be used in an in-place operation (both as input and output) in the execution environment. More...
 
template<typename DeviceAdapterTag >
VTKM_CONT void PrepareForDevice (DeviceAdapterTag) const
 Gets this array handle ready to interact with the given device. More...
 
VTKM_CONT void SyncControlArray () const
 Synchronizes the control array with the execution array. More...
 
VTKM_CONT void ReleaseResourcesExecutionInternal ()
 
VTKM_CONT DeviceAdapterId GetDeviceAdapterId () const
 Returns the DeviceAdapterId for the current device. More...
 
VTKM_CONT ArrayHandle (const std::shared_ptr< InternalStruct > &i)
 

Public Attributes

std::shared_ptr< InternalStructInternals
 

Private Types

using ExecutionManagerType = vtkm::cont::internal::ArrayHandleExecutionManagerBase< T, StorageTag_ >
 

Detailed Description

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
class vtkm::cont::ArrayHandle< T, StorageTag_ >

Manages an array-worth of data.

ArrayHandle manages as array of data that can be manipulated by VTKm algorithms. The ArrayHandle may have up to two copies of the array, one for the control environment and one for the execution environment, although depending on the device and how the array is being used, the ArrayHandle will only have one copy when possible.

An ArrayHandle can be constructed one of two ways. Its default construction creates an empty, unallocated array that can later be allocated and filled either by the user or a VTKm algorithm. The ArrayHandle can also be constructed with iterators to a user's array. In this case the ArrayHandle will keep a reference to this array but will throw an exception if asked to re-allocate to a larger size.

ArrayHandle behaves like a shared smart pointer in that when it is copied each copy holds a reference to the same array. These copies are reference counted so that when all copies of the ArrayHandle are destroyed, any allocated memory is released.

Member Typedef Documentation

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
using vtkm::cont::ArrayHandle< T, StorageTag_ >::ExecutionManagerType = vtkm::cont::internal::ArrayHandleExecutionManagerBase<T, StorageTag_>
private
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
using vtkm::cont::ArrayHandle< T, StorageTag_ >::PortalConstControl = typename StorageType::PortalConstType
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
using vtkm::cont::ArrayHandle< T, StorageTag_ >::PortalControl = typename StorageType::PortalType
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
using vtkm::cont::ArrayHandle< T, StorageTag_ >::StorageTag = StorageTag_
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
using vtkm::cont::ArrayHandle< T, StorageTag_ >::StorageType = vtkm::cont::internal::Storage<T, StorageTag_>
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
using vtkm::cont::ArrayHandle< T, StorageTag_ >::ValueType = T

Constructor & Destructor Documentation

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT vtkm::cont::ArrayHandle< T, StorageTag_ >::ArrayHandle ( )

Constructs an empty ArrayHandle.

Typically used for output or intermediate arrays that will be filled by a VTKm algorithm.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
vtkm::cont::ArrayHandle< T, StorageTag_ >::ArrayHandle ( const vtkm::cont::ArrayHandle< ValueType, StorageTag > &  src)

Copy constructor.

Implemented so that it is defined exclusively in the control environment. If there is a separate device for the execution environment (for example, with CUDA), then the automatically generated copy constructor could be created for all devices, and it would not be valid for all devices.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
vtkm::cont::ArrayHandle< T, StorageTag_ >::ArrayHandle ( vtkm::cont::ArrayHandle< ValueType, StorageTag > &&  src)
noexcept

Move constructor.

Implemented so that it is defined exclusively in the control environment. If there is a separate device for the execution environment (for example, with CUDA), then the automatically generated move constructor could be created for all devices, and it would not be valid for all devices.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
vtkm::cont::ArrayHandle< T, StorageTag_ >::ArrayHandle ( const StorageType storage)

Special constructor for subclass specializations that need to set the initial state of the control array.

When this constructor is used, it is assumed that the control array is valid.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
vtkm::cont::ArrayHandle< T, StorageTag_ >::ArrayHandle ( StorageType &&  storage)
noexcept

Special constructor for subclass specializations that need to set the initial state of the control array.

When this constructor is used, it is assumed that the control array is valid.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
vtkm::cont::ArrayHandle< T, StorageTag_ >::~ArrayHandle ( )

Destructs an empty ArrayHandle.

Implemented so that it is defined exclusively in the control environment. If there is a separate device for the execution environment (for example, with CUDA), then the automatically generated destructor could be created for all devices, and it would not be valid for all devices.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT vtkm::cont::ArrayHandle< T, StorageTag_ >::ArrayHandle ( const std::shared_ptr< InternalStruct > &  i)
inline

Member Function Documentation

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT void vtkm::cont::ArrayHandle< T, StorageTag_ >::Allocate ( vtkm::Id  numberOfValues)
inline

Allocates an array large enough to hold the given number of values.

The allocation may be done on an already existing array, but can wipe out any data already in the array. This method can throw ErrorBadAllocation if the array cannot be allocated or ErrorBadValue if the allocation is not feasible (for example, the array storage is read-only).

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT DeviceAdapterId vtkm::cont::ArrayHandle< T, StorageTag_ >::GetDeviceAdapterId ( ) const
inline

Returns the DeviceAdapterId for the current device.

If there is no device with an up-to-date copy of the data, VTKM_DEVICE_ADAPTER_UNDEFINED is returned.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT vtkm::Id vtkm::cont::ArrayHandle< T, StorageTag_ >::GetNumberOfValues ( ) const

Returns the number of entries in the array.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT PortalConstControl vtkm::cont::ArrayHandle< T, StorageTag_ >::GetPortalConstControl ( ) const

Get the array portal of the control array.

Since worklet invocations are asynchronous and this routine is a synchronization point, exceptions maybe thrown for errors from previously executed worklets.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT PortalControl vtkm::cont::ArrayHandle< T, StorageTag_ >::GetPortalControl ( )

Get the array portal of the control array.

Since worklet invocations are asynchronous and this routine is a synchronization point, exceptions maybe thrown for errors from previously executed worklets.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT StorageType& vtkm::cont::ArrayHandle< T, StorageTag_ >::GetStorage ( )

Get the storage.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT const StorageType& vtkm::cont::ArrayHandle< T, StorageTag_ >::GetStorage ( ) const

Get the storage.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT bool vtkm::cont::ArrayHandle< T, StorageTag_ >::operator!= ( const ArrayHandle< ValueType, StorageTag > &  rhs) const
inline
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
template<typename VT , typename ST >
VTKM_CONT bool vtkm::cont::ArrayHandle< T, StorageTag_ >::operator!= ( const ArrayHandle< VT, ST > &  ) const
inline
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT vtkm::cont::ArrayHandle<ValueType, StorageTag>& vtkm::cont::ArrayHandle< T, StorageTag_ >::operator= ( const vtkm::cont::ArrayHandle< ValueType, StorageTag > &  src)

Copies an ArrayHandle.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT vtkm::cont::ArrayHandle<ValueType, StorageTag>& vtkm::cont::ArrayHandle< T, StorageTag_ >::operator= ( vtkm::cont::ArrayHandle< ValueType, StorageTag > &&  src)
noexcept

Move and Assignment of an ArrayHandle.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT bool vtkm::cont::ArrayHandle< T, StorageTag_ >::operator== ( const ArrayHandle< ValueType, StorageTag > &  rhs) const
inline

Like a pointer, two ArrayHandles are considered equal if they point to the same location in memory.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
template<typename VT , typename ST >
VTKM_CONT bool vtkm::cont::ArrayHandle< T, StorageTag_ >::operator== ( const ArrayHandle< VT, ST > &  ) const
inline
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
template<typename DeviceAdapterTag >
VTKM_CONT void vtkm::cont::ArrayHandle< T, StorageTag_ >::PrepareForDevice ( DeviceAdapterTag  ) const

Gets this array handle ready to interact with the given device.

If the array handle has already interacted with this device, then this method does nothing. Although the internal state of this class can change, the method is declared const because logically the data does not.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
template<typename DeviceAdapterTag >
VTKM_CONT ExecutionTypes<DeviceAdapterTag>::Portal vtkm::cont::ArrayHandle< T, StorageTag_ >::PrepareForInPlace ( DeviceAdapterTag  )

Prepares this array to be used in an in-place operation (both as input and output) in the execution environment.

If necessary, copies data to the execution environment. Can throw an exception if this array does not yet contain any data. Returns a portal that can be used in code running in the execution environment.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
template<typename DeviceAdapterTag >
VTKM_CONT ExecutionTypes<DeviceAdapterTag>::PortalConst vtkm::cont::ArrayHandle< T, StorageTag_ >::PrepareForInput ( DeviceAdapterTag  ) const

Prepares this array to be used as an input to an operation in the execution environment.

If necessary, copies data to the execution environment. Can throw an exception if this array does not yet contain any data. Returns a portal that can be used in code running in the execution environment.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
template<typename DeviceAdapterTag >
VTKM_CONT ExecutionTypes<DeviceAdapterTag>::Portal vtkm::cont::ArrayHandle< T, StorageTag_ >::PrepareForOutput ( vtkm::Id  numberOfValues,
DeviceAdapterTag   
)

Prepares (allocates) this array to be used as an output from an operation in the execution environment.

The internal state of this class is set to have valid data in the execution array with the assumption that the array will be filled soon (i.e. before any other methods of this object are called). Returns a portal that can be used in code running in the execution environment.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT void vtkm::cont::ArrayHandle< T, StorageTag_ >::ReleaseResources ( )
inline

Releases all resources in both the control and execution environments.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT void vtkm::cont::ArrayHandle< T, StorageTag_ >::ReleaseResourcesExecution ( )
inline

Releases any resources being used in the execution environment (that are not being shared by the control environment).

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT void vtkm::cont::ArrayHandle< T, StorageTag_ >::ReleaseResourcesExecutionInternal ( )
inline
template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
void vtkm::cont::ArrayHandle< T, StorageTag_ >::Shrink ( vtkm::Id  numberOfValues)

Reduces the size of the array without changing its values.

This method allows you to resize the array without reallocating it. The number of entries in the array is changed to numberOfValues. The data in the array (from indices 0 to numberOfValues - 1) are the same, but numberOfValues must be equal or less than the preexisting size (returned from GetNumberOfValues). That is, this method can only be used to shorten the array, not lengthen.

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
VTKM_CONT void vtkm::cont::ArrayHandle< T, StorageTag_ >::SyncControlArray ( ) const

Synchronizes the control array with the execution array.

If either the user array or control array is already valid, this method does nothing (because the data is already available in the control environment). Although the internal state of this class can change, the method is declared const because logically the data does not.

Member Data Documentation

template<typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
std::shared_ptr<InternalStruct> vtkm::cont::ArrayHandle< T, StorageTag_ >::Internals

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