Manages an array-worth of data. More...
#include <ArrayHandle.h>
Public Types | |
| using | ValueType = T |
| using | StorageTag = StorageTag_ |
| using | StorageType = vtkm::cont::internal::Storage< ValueType, StorageTag > |
| using | ReadPortalType = typename StorageType::ReadPortalType |
| using | WritePortalType = typename StorageType::WritePortalType |
Public Member Functions | |
| 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 std::vector< vtkm::cont::internal::Buffer > &buffers) | |
| Special constructor for subclass specializations that need to set the initial state array. More... | |
| ArrayHandle (std::vector< vtkm::cont::internal::Buffer > &&buffers) noexcept | |
| Special constructor for subclass specializations that need to set the initial state array. More... | |
| ~ArrayHandle () | |
| Destructs an empty ArrayHandle. More... | |
| vtkm::cont::ArrayHandle< ValueType, StorageTag > & | operator= (const vtkm::cont::ArrayHandle< ValueType, StorageTag > &src) |
| Shallow copies an ArrayHandle. More... | |
| vtkm::cont::ArrayHandle< ValueType, StorageTag > & | operator= (vtkm::cont::ArrayHandle< ValueType, StorageTag > &&src) noexcept |
| Move and Assignment of an ArrayHandle. More... | |
| 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... | |
| bool | operator!= (const ArrayHandle< ValueType, StorageTag > &rhs) const |
| template<typename VT , typename ST > | |
| bool | operator== (const ArrayHandle< VT, ST > &) const |
| template<typename VT , typename ST > | |
| bool | operator!= (const ArrayHandle< VT, ST > &) const |
| StorageType | GetStorage () const |
| Get the storage. More... | |
| ReadPortalType | ReadPortal () const |
| Get an array portal that can be used in the control environment. More... | |
| ReadPortalType | ReadPortal (vtkm::cont::Token &token) const |
| WritePortalType | WritePortal () const |
| Get an array portal that can be used in the control environment. More... | |
| WritePortalType | WritePortal (vtkm::cont::Token &token) const |
| Get an array portal that can be used in the control environment. More... | |
| vtkm::Id | GetNumberOfValues () const |
| Returns the number of entries in the array. More... | |
| vtkm::IdComponent | GetNumberOfComponentsFlat () const |
| Returns the total number of components for each value in the array. More... | |
| void | Allocate (vtkm::Id numberOfValues, vtkm::CopyFlag preserve, vtkm::cont::Token &token) const |
| Allocates an array large enough to hold the given number of values. More... | |
| void | Allocate (vtkm::Id numberOfValues, vtkm::CopyFlag preserve=vtkm::CopyFlag::Off) const |
| Allocates an array large enough to hold the given number of values. More... | |
| void | AllocateAndFill (vtkm::Id numberOfValues, const ValueType &fillValue, vtkm::CopyFlag preserve, vtkm::cont::Token &token) const |
| Allocates an array and fills it with an initial value. More... | |
| void | AllocateAndFill (vtkm::Id numberOfValues, const ValueType &fillValue, vtkm::CopyFlag preserve=vtkm::CopyFlag::Off) const |
| Allocates an array and fills it with an initial value. More... | |
| void | Fill (const ValueType &fillValue, vtkm::Id startIndex, vtkm::Id endIndex, vtkm::cont::Token &token) const |
| Fills the array with a given value. More... | |
| void | Fill (const ValueType &fillValue, vtkm::Id startIndex, vtkm::Id endIndex) const |
| Fills the array with a given value. More... | |
| void | Fill (const ValueType &fillValue, vtkm::Id startIndex=0) const |
| Fills the array with a given value. More... | |
| void | ReleaseResourcesExecution () const |
| Releases any resources being used in the execution environment (that are not being shared by the control environment). More... | |
| void | ReleaseResources () const |
| Releases all resources in both the control and execution environments. More... | |
| ReadPortalType | PrepareForInput (vtkm::cont::DeviceAdapterId device, vtkm::cont::Token &token) const |
| Prepares this array to be used as an input to an operation in the execution environment. More... | |
| WritePortalType | PrepareForInPlace (vtkm::cont::DeviceAdapterId device, vtkm::cont::Token &token) const |
| Prepares this array to be used in an in-place operation (both as input and output) in the execution environment. More... | |
| WritePortalType | PrepareForOutput (vtkm::Id numberOfValues, vtkm::cont::DeviceAdapterId device, vtkm::cont::Token &token) const |
| Prepares (allocates) this array to be used as an output from an operation in the execution environment. More... | |
| bool | IsOnDevice (vtkm::cont::DeviceAdapterId device) const |
| Returns true if the ArrayHandle's data is on the given device. More... | |
| bool | IsOnHost () const |
| Returns true if the ArrayHandle's data is on the host. More... | |
| void | SyncControlArray () const |
| Synchronizes the control array with the execution array. More... | |
| void | Enqueue (const vtkm::cont::Token &token) const |
| Enqueue a token for access to this ArrayHandle. More... | |
| void | DeepCopyFrom (const vtkm::cont::ArrayHandle< ValueType, StorageTag > &source) const |
| Deep copies the data in the array. More... | |
| const std::vector< vtkm::cont::internal::Buffer > & | GetBuffers () const |
Returns the internal Buffer structures that hold the data. More... | |
| std::vector< vtkm::cont::internal::Buffer > & | GetBuffers () |
Protected Member Functions | |
| void | SetBuffer (vtkm::IdComponent index, const vtkm::cont::internal::Buffer &buffer) |
| void | SetBuffers (const std::vector< vtkm::cont::internal::Buffer > &buffers) |
| void | SetBuffers (std::vector< vtkm::cont::internal::Buffer > &&buffers) |
Private Attributes | |
| std::vector< vtkm::cont::internal::Buffer > | Buffers |
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 is often constructed by instantiating one of the ArrayHandle subclasses. Several basic ArrayHandle types can also be constructed directly and then allocated. The ArrayHandleBasic subclass provides mechanisms for importing user arrays into an ArrayHandle.
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
◆ ReadPortalType
| using vtkm::cont::ArrayHandle< T, StorageTag_ >::ReadPortalType = typename StorageType::ReadPortalType |
◆ StorageTag
| using vtkm::cont::ArrayHandle< T, StorageTag_ >::StorageTag = StorageTag_ |
◆ StorageType
| using vtkm::cont::ArrayHandle< T, StorageTag_ >::StorageType = vtkm::cont::internal::Storage<ValueType, StorageTag> |
◆ ValueType
| using vtkm::cont::ArrayHandle< T, StorageTag_ >::ValueType = T |
◆ WritePortalType
| using vtkm::cont::ArrayHandle< T, StorageTag_ >::WritePortalType = typename StorageType::WritePortalType |
Constructor & Destructor Documentation
◆ ArrayHandle() [1/5]
|
inline |
Constructs an empty ArrayHandle.
◆ ArrayHandle() [2/5]
|
inline |
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.
◆ ArrayHandle() [3/5]
|
inlinenoexcept |
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.
◆ ArrayHandle() [4/5]
|
inlineexplicit |
Special constructor for subclass specializations that need to set the initial state array.
Used when pulling data from other sources.
◆ ArrayHandle() [5/5]
|
inlineexplicitnoexcept |
Special constructor for subclass specializations that need to set the initial state array.
Used when pulling data from other sources.
◆ ~ArrayHandle()
|
inline |
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.
Member Function Documentation
◆ Allocate() [1/2]
|
inline |
Allocates an array large enough to hold the given number of values.
The allocation may be done on an already existing array. If so, then the data are preserved as best as possible if the preserve flag is set to vtkm::CopyFlag::On. If the preserve flag is set to vtkm::CopyFlag::Off (the default), any existing data could be wiped out.
This method can throw vtkm::cont::ErrorBadAllocation if the array cannot be allocated or vtkm::cont::ErrorBadValue if the allocation is not feasible (for example, the array storage is read-only).
◆ Allocate() [2/2]
|
inline |
Allocates an array large enough to hold the given number of values.
The allocation may be done on an already existing array. If so, then the data are preserved as best as possible if the preserve flag is set to vtkm::CopyFlag::On. If the preserve flag is set to vtkm::CopyFlag::Off (the default), any existing data could be wiped out.
This method can throw vtkm::cont::ErrorBadAllocation if the array cannot be allocated or vtkm::cont::ErrorBadValue if the allocation is not feasible (for example, the array storage is read-only).
◆ AllocateAndFill() [1/2]
|
inline |
Allocates an array and fills it with an initial value.
AllocateAndFill behaves similar to Allocate except that after allocation it fills the array with a given fillValue. This method is convenient when you wish to initialize the array.
If the preserve flag is vtkm::CopyFlag::On, then any data that existed before the call to AllocateAndFill will remain after the call (assuming the new array size is large enough). If the array size is expanded, then the new values at the end will be filled.
If the preserve flag is vtkm::CopyFlag::Off (the default), the entire array is filled with the given fillValue.
◆ AllocateAndFill() [2/2]
|
inline |
Allocates an array and fills it with an initial value.
AllocateAndFill behaves similar to Allocate except that after allocation it fills the array with a given fillValue. This method is convenient when you wish to initialize the array.
If the preserve flag is vtkm::CopyFlag::On, then any data that existed before the call to AllocateAndFill will remain after the call (assuming the new array size is large enough). If the array size is expanded, then the new values at the end will be filled.
If the preserve flag is vtkm::CopyFlag::Off (the default), the entire array is filled with the given fillValue.
◆ DeepCopyFrom()
|
inline |
Deep copies the data in the array.
Takes the data that is in source and copies that data into this array.
◆ Enqueue()
|
inline |
Enqueue a token for access to this ArrayHandle.
This method places the given Token into the queue of Tokens waiting for access to this ArrayHandle and then returns immediately. When this token is later used to get data from this ArrayHandle (for example, in a call to PrepareForInput), it will use this place in the queue while waiting for access.
This method is to be used to ensure that a set of accesses to an ArrayHandle that happen on multiple threads occur in a specified order. For example, if you spawn of a job to modify data in an ArrayHandle and then spawn off a job that reads that same data, you need to make sure that the first job gets access to the ArrayHandle before the second. If they both just attempt to call their respective Prepare methods, there is no guarantee which order they will occur. Having the spawning thread first call this method will ensure the order.
- Warning
- After calling this method it is required to subsequently call a method like one of the
Preparemethods that attaches the token to thisArrayHandle. Otherwise, the enqueued token will block any subsequent access to theArrayHandle, even if theTokenis destroyed.
◆ Fill() [1/3]
|
inline |
Fills the array with a given value.
After calling this method, every entry in the array from startIndex (inclusive) to endIndex (exclusive) of the array is set to fillValue. If startIndex or endIndex is not specified, then the fill happens from the begining or end, respectively.
◆ Fill() [2/3]
|
inline |
Fills the array with a given value.
After calling this method, every entry in the array from startIndex (inclusive) to endIndex (exclusive) of the array is set to fillValue. If startIndex or endIndex is not specified, then the fill happens from the begining or end, respectively.
◆ Fill() [3/3]
|
inline |
Fills the array with a given value.
After calling this method, every entry in the array from startIndex (inclusive) to endIndex (exclusive) of the array is set to fillValue. If startIndex or endIndex is not specified, then the fill happens from the begining or end, respectively.
◆ GetBuffers() [1/2]
|
inline |
◆ GetBuffers() [2/2]
|
inline |
Returns the internal Buffer structures that hold the data.
Note that great care should be taken when modifying buffers outside of the ArrayHandle.
◆ GetNumberOfComponentsFlat()
|
inline |
Returns the total number of components for each value in the array.
If the array holds vtkm::Vec objects, this will return the total number of components in each value assuming the object is flattened out to one level of Vec objects. If the array holds a basic C type (such as float), this will return 1. If the array holds a simple Vec (such as vtkm::Vec3f), this will return the number of components (in this case 3). If the array holds a hierarchy of Vecs (such as vtkm::Vec<vtkm::Vec3f, 2>), this will return the total number of vecs (in this case 6).
If this object is holding an array where the number of components can be selected at runtime (for example, vtkm::cont::ArrayHandleRuntimeVec), this method will still return the correct number of components. However, if each value in the array can be a Vec of a different size (such as vtkm::cont::ArrayHandleGroupVecVariable), this method will return 0 (because there is no consistent answer).
◆ GetNumberOfValues()
|
inline |
Returns the number of entries in the array.
◆ GetStorage()
|
inline |
Get the storage.
◆ IsOnDevice()
|
inline |
Returns true if the ArrayHandle's data is on the given device.
If the data are on the given device, then preparing for that device should not require any data movement.
◆ IsOnHost()
|
inline |
Returns true if the ArrayHandle's data is on the host.
If the data are on the given device, then calling ReadPortal or WritePortal should not require any data movement.
◆ operator!=() [1/2]
|
inline |
◆ operator!=() [2/2]
|
inline |
◆ operator=() [1/2]
|
inline |
Shallow copies an ArrayHandle.
◆ operator=() [2/2]
|
inlinenoexcept |
Move and Assignment of an ArrayHandle.
◆ operator==() [1/2]
|
inline |
Like a pointer, two ArrayHandles are considered equal if they point to the same location in memory.
◆ operator==() [2/2]
|
inline |
◆ PrepareForInPlace()
|
inline |
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.
The Token object provided will be attached to this ArrayHandle. The returned portal is guaranteed to be valid while the Token is still attached and in scope. Other operations on this ArrayHandle that would invalidate the returned portal will block until the Token is released. Likewise, this method will block if another Token is already attached. This can potentially lead to deadlocks.
◆ PrepareForInput()
|
inline |
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.
The Token object provided will be attached to this ArrayHandle. The returned portal is guaranteed to be valid while the Token is still attached and in scope. Other operations on this ArrayHandle that would invalidate the returned portal will block until the Token is released. Likewise, this method will block if another Token is already attached. This can potentially lead to deadlocks.
◆ PrepareForOutput()
|
inline |
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.
The Token object provided will be attached to this ArrayHandle. The returned portal is guaranteed to be valid while the Token is still attached and in scope. Other operations on this ArrayHandle that would invalidate the returned portal will block until the Token is released. Likewise, this method will block if another Token is already attached. This can potentially lead to deadlocks.
◆ ReadPortal() [1/2]
|
inline |
Get an array portal that can be used in the control environment.
The returned array can be used in the control environment to read values from the array. (It is not possible to write to the returned portal. That is Get will work on the portal, but Set will not.)
Note: The returned portal cannot be used in the execution environment. This is because the portal will not work on some devices like GPUs. To get a portal that will work in the execution environment, use PrepareForInput.
◆ ReadPortal() [2/2]
|
inline |
◆ ReleaseResources()
|
inline |
Releases all resources in both the control and execution environments.
◆ ReleaseResourcesExecution()
|
inline |
Releases any resources being used in the execution environment (that are not being shared by the control environment).
◆ SetBuffer()
|
inlineprotected |
◆ SetBuffers() [1/2]
|
inlineprotected |
◆ SetBuffers() [2/2]
|
inlineprotected |
◆ SyncControlArray()
|
inline |
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.
◆ WritePortal() [1/2]
|
inline |
Get an array portal that can be used in the control environment.
The returned array can be used in the control environment to reand and write values to the array.
Note: The returned portal cannot be used in the execution environment. This is because the portal will not work on some devices like GPUs. To get a portal that will work in the execution environment, use PrepareForInput.
◆ WritePortal() [2/2]
|
inline |
Get an array portal that can be used in the control environment.
The returned array can be used in the control environment to reand and write values to the array.
Note: The returned portal cannot be used in the execution environment. This is because the portal will not work on some devices like GPUs. To get a portal that will work in the execution environment, use PrepareForInput.
Member Data Documentation
◆ Buffers
|
mutableprivate |
The documentation for this class was generated from the following file:
