ArrayHandle.h

Go to the documentation of this file.

//============================================================================
//  Copyright (c) Kitware, Inc.
//  All rights reserved.
//  See LICENSE.txt for details.
//
//  This software is distributed WITHOUT ANY WARRANTY; without even
//  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
//  PURPOSE.  See the above copyright notice for more information.
//============================================================================
#ifndef vtk_m_cont_ArrayHandle_h
#define vtk_m_cont_ArrayHandle_h
 
#include <vtkm/cont/vtkm_cont_export.h>
 
#include <vtkm/Assert.h>
#include <vtkm/Flags.h>
#include <vtkm/Types.h>
 
#include <vtkm/cont/DeviceAdapterList.h>
#include <vtkm/cont/ErrorBadValue.h>
#include <vtkm/cont/ErrorInternal.h>
#include <vtkm/cont/Storage.h>
#include <vtkm/cont/Token.h>
 
#include <vtkm/internal/ArrayPortalHelpers.h>
 
#include <algorithm>
#include <deque>
#include <iterator>
#include <memory>
#include <mutex>
#include <vector>
 
#include <vtkm/cont/internal/Buffer.h>
 
namespace vtkm
{
namespace cont
{
 
// Normally this would be defined in ArrayHandleBasic.h, but we need this declared early for
// the default storage.
 
struct VTKM_ALWAYS_EXPORT StorageTagBasic
{
};
}
} // namespace vtkm::cont
 
#if VTKM_STORAGE == VTKM_STORAGE_BASIC
 
#define VTKM_DEFAULT_STORAGE_TAG ::vtkm::cont::StorageTagBasic
 
#elif VTKM_STORAGE == VTKM_STORAGE_ERROR
 
#include <vtkm/cont/internal/StorageError.h>
#define VTKM_DEFAULT_STORAGE_TAG ::vtkm::cont::internal::StorageTagError
 
#elif (VTKM_STORAGE == VTKM_STORAGE_UNDEFINED) || !defined(VTKM_STORAGE)
 
#ifndef VTKM_DEFAULT_STORAGE_TAG
#warning If array storage is undefined, VTKM_DEFAULT_STORAGE_TAG must be defined.
#endif
 
#endif
 
namespace vtkm
{
namespace cont
{
 
namespace internal
{
 
class VTKM_CONT_EXPORT ArrayHandleBase
{
};
 
template <typename T, typename StorageTag>
using IsValidArrayHandle =
  std::integral_constant<bool,
                         !(std::is_base_of<vtkm::cont::internal::UndefinedStorage,
                                           vtkm::cont::internal::Storage<T, StorageTag>>::value)>;
 
template <typename T, typename StorageTag>
using IsInvalidArrayHandle =
  std::integral_constant<bool, !IsValidArrayHandle<T, StorageTag>::value>;
 
template <typename ArrayHandle>
using IsWritableArrayHandle =
  vtkm::internal::PortalSupportsSets<typename std::decay<ArrayHandle>::type::WritePortalType>;
 
template <typename T>
struct ArrayHandleCheck
  : std::is_base_of<vtkm::cont::internal::ArrayHandleBase, std::decay_t<T>>::type
{
};
 
#define VTKM_IS_ARRAY_HANDLE(T) VTKM_STATIC_ASSERT(::vtkm::cont::internal::ArrayHandleCheck<T>{})
 
} // namespace internal
 
namespace detail
{
 
template <typename T>
struct GetTypeInParentheses;
template <typename T>
struct GetTypeInParentheses<void(T)>
{
  using type = T;
};
 
} // namespace detail
 
// Implementation for VTKM_ARRAY_HANDLE_SUBCLASS macros
#define VTK_M_ARRAY_HANDLE_SUBCLASS_IMPL(classname, fullclasstype, superclass, typename__)         \
  using Thisclass = typename__ vtkm::cont::detail::GetTypeInParentheses<void fullclasstype>::type; \
  using Superclass = typename__ vtkm::cont::detail::GetTypeInParentheses<void superclass>::type;   \
                                                                                                   \
  VTKM_IS_ARRAY_HANDLE(Superclass);                                                                \
                                                                                                   \
  VTKM_CONT                                                                                        \
  classname()                                                                                      \
    : Superclass()                                                                                 \
  {                                                                                                \
  }                                                                                                \
                                                                                                   \
  VTKM_CONT                                                                                        \
  classname(const Thisclass& src)                                                                  \
    : Superclass(src)                                                                              \
  {                                                                                                \
  }                                                                                                \
                                                                                                   \
  VTKM_CONT                                                                                        \
  classname(Thisclass&& src) noexcept                                                              \
    : Superclass(std::move(src))                                                                   \
  {                                                                                                \
  }                                                                                                \
                                                                                                   \
  VTKM_CONT                                                                                        \
  classname(const vtkm::cont::ArrayHandle<typename__ Superclass::ValueType,                        \
                                          typename__ Superclass::StorageTag>& src)                 \
    : Superclass(src)                                                                              \
  {                                                                                                \
  }                                                                                                \
                                                                                                   \
  VTKM_CONT                                                                                        \
  classname(vtkm::cont::ArrayHandle<typename__ Superclass::ValueType,                              \
                                    typename__ Superclass::StorageTag>&& src) noexcept             \
    : Superclass(std::move(src))                                                                   \
  {                                                                                                \
  }                                                                                                \
                                                                                                   \
  VTKM_CONT                                                                                        \
  Thisclass& operator=(const Thisclass& src)                                                       \
  {                                                                                                \
    this->Superclass::operator=(src);                                                              \
    return *this;                                                                                  \
  }                                                                                                \
                                                                                                   \
  VTKM_CONT                                                                                        \
  Thisclass& operator=(Thisclass&& src) noexcept                                                   \
  {                                                                                                \
    this->Superclass::operator=(std::move(src));                                                   \
    return *this;                                                                                  \
  }                                                                                                \
                                                                                                   \
  using ValueType = typename__ Superclass::ValueType;                                              \
  using StorageTag = typename__ Superclass::StorageTag
 
#define VTKM_ARRAY_HANDLE_SUBCLASS(classname, fullclasstype, superclass) \
  VTK_M_ARRAY_HANDLE_SUBCLASS_IMPL(classname, fullclasstype, superclass, typename)
 
#define VTKM_ARRAY_HANDLE_SUBCLASS_NT(classname, superclass) \
  VTK_M_ARRAY_HANDLE_SUBCLASS_IMPL(classname, (classname), superclass, )
 
namespace detail
{
 
VTKM_CONT_EXPORT VTKM_CONT void ArrayHandleReleaseResourcesExecution(
  const std::vector<vtkm::cont::internal::Buffer>& buffers);
 
VTKM_CONT_EXPORT VTKM_CONT bool ArrayHandleIsOnDevice(
  const std::vector<vtkm::cont::internal::Buffer>& buffers,
  vtkm::cont::DeviceAdapterId device);
 
} // namespace detail
 
template <typename T, typename StorageTag_ = VTKM_DEFAULT_STORAGE_TAG>
class VTKM_ALWAYS_EXPORT ArrayHandle : public internal::ArrayHandleBase
{
  VTKM_STATIC_ASSERT_MSG(
    (internal::IsValidArrayHandle<T, StorageTag_>::value),
    "Attempted to create an ArrayHandle with an invalid type/storage combination.");
 
public:
  using ValueType = T;
  using StorageTag = StorageTag_;
  using StorageType = vtkm::cont::internal::Storage<ValueType, StorageTag>;
 
  using ReadPortalType = typename StorageType::ReadPortalType;
  using WritePortalType = typename StorageType::WritePortalType;
 
  VTKM_CONT ArrayHandle()
    : Buffers(StorageType::CreateBuffers())
  {
  }
 
  VTKM_CONT ArrayHandle(const vtkm::cont::ArrayHandle<ValueType, StorageTag>& src)
    : Buffers(src.Buffers)
  {
  }
 
  VTKM_CONT ArrayHandle(vtkm::cont::ArrayHandle<ValueType, StorageTag>&& src) noexcept
    : Buffers(std::move(src.Buffers))
  {
  }
 
  VTKM_CONT ArrayHandle(const std::vector<vtkm::cont::internal::Buffer>& buffers)
    : Buffers(buffers)
  {
  }
 
  VTKM_CONT ArrayHandle(std::vector<vtkm::cont::internal::Buffer>&& buffers) noexcept
    : Buffers(std::move(buffers))
  {
  }
 
  VTKM_CONT ~ArrayHandle() {}
 
  VTKM_CONT
  vtkm::cont::ArrayHandle<ValueType, StorageTag>& operator=(
    const vtkm::cont::ArrayHandle<ValueType, StorageTag>& src)
  {
    this->Buffers = src.Buffers;
    return *this;
  }
 
  VTKM_CONT
  vtkm::cont::ArrayHandle<ValueType, StorageTag>& operator=(
    vtkm::cont::ArrayHandle<ValueType, StorageTag>&& src) noexcept
  {
    this->Buffers = std::move(src.Buffers);
    return *this;
  }
 
  VTKM_CONT
  bool operator==(const ArrayHandle<ValueType, StorageTag>& rhs) const
  {
    return this->Buffers == rhs.Buffers;
  }
 
  VTKM_CONT
  bool operator!=(const ArrayHandle<ValueType, StorageTag>& rhs) const
  {
    return this->Buffers != rhs.Buffers;
  }
 
  template <typename VT, typename ST>
  VTKM_CONT bool operator==(const ArrayHandle<VT, ST>&) const
  {
    return false; // different valuetype and/or storage
  }
 
  template <typename VT, typename ST>
  VTKM_CONT bool operator!=(const ArrayHandle<VT, ST>&) const
  {
    return true; // different valuetype and/or storage
  }
 
  VTKM_CONT StorageType GetStorage() const { return StorageType{}; }
 
  VTKM_CONT ReadPortalType ReadPortal() const
  {
    vtkm::cont::Token token;
    return this->ReadPortal(token);
  }
  VTKM_CONT ReadPortalType ReadPortal(vtkm::cont::Token& token) const
  {
    return StorageType::CreateReadPortal(
      this->GetBuffers(), vtkm::cont::DeviceAdapterTagUndefined{}, token);
  }
 
  VTKM_CONT WritePortalType WritePortal() const
  {
    vtkm::cont::Token token;
    return this->WritePortal(token);
  }
  VTKM_CONT WritePortalType WritePortal(vtkm::cont::Token& token) const
  {
    return StorageType::CreateWritePortal(
      this->GetBuffers(), vtkm::cont::DeviceAdapterTagUndefined{}, token);
  }
 
  VTKM_CONT vtkm::Id GetNumberOfValues() const
  {
    return StorageType::GetNumberOfValues(this->GetBuffers());
  }
 
  VTKM_CONT void Allocate(vtkm::Id numberOfValues,
                          vtkm::CopyFlag preserve,
                          vtkm::cont::Token& token) const
  {
    StorageType::ResizeBuffers(numberOfValues, this->GetBuffers(), preserve, token);
  }
 
  VTKM_CONT void Allocate(vtkm::Id numberOfValues,
                          vtkm::CopyFlag preserve = vtkm::CopyFlag::Off) const
  {
    vtkm::cont::Token token;
    this->Allocate(numberOfValues, preserve, token);
  }
 
  VTKM_CONT void AllocateAndFill(vtkm::Id numberOfValues,
                                 const ValueType& fillValue,
                                 vtkm::CopyFlag preserve,
                                 vtkm::cont::Token& token) const
  {
    // Note that there is a slight potential for a race condition here. It is possible for someone
    // else to resize the array in between getting the startIndex and locking the array in the
    // Allocate call. If there really are 2 threads trying to allocate this array at the same time,
    // you probably have bigger problems than filling at the wrong index.
    vtkm::Id startIndex = (preserve == vtkm::CopyFlag::On) ? this->GetNumberOfValues() : 0;
 
    this->Allocate(numberOfValues, preserve, token);
 
    if (startIndex < numberOfValues)
    {
      this->Fill(fillValue, startIndex, numberOfValues, token);
    }
  }
 
  VTKM_CONT void AllocateAndFill(vtkm::Id numberOfValues,
                                 const ValueType& fillValue,
                                 vtkm::CopyFlag preserve = vtkm::CopyFlag::Off) const
  {
    vtkm::cont::Token token;
    this->AllocateAndFill(numberOfValues, fillValue, preserve, token);
  }
 
  VTKM_CONT void Fill(const ValueType& fillValue,
                      vtkm::Id startIndex,
                      vtkm::Id endIndex,
                      vtkm::cont::Token& token) const
  {
    StorageType::Fill(this->GetBuffers(), fillValue, startIndex, endIndex, token);
  }
  VTKM_CONT void Fill(const ValueType& fillValue, vtkm::Id startIndex, vtkm::Id endIndex) const
  {
    vtkm::cont::Token token;
    this->Fill(fillValue, startIndex, endIndex, token);
  }
  VTKM_CONT void Fill(const ValueType& fillValue, vtkm::Id startIndex = 0) const
  {
    vtkm::cont::Token token;
    this->Fill(fillValue, startIndex, this->GetNumberOfValues(), token);
  }
 
  VTKM_CONT void ReleaseResourcesExecution() const
  {
    detail::ArrayHandleReleaseResourcesExecution(this->Buffers);
  }
 
  VTKM_CONT void ReleaseResources() const { this->Allocate(0); }
 
  VTKM_CONT ReadPortalType PrepareForInput(vtkm::cont::DeviceAdapterId device,
                                           vtkm::cont::Token& token) const
  {
    return StorageType::CreateReadPortal(this->GetBuffers(), device, token);
  }
 
  VTKM_CONT WritePortalType PrepareForInPlace(vtkm::cont::DeviceAdapterId device,
                                              vtkm::cont::Token& token) const
  {
    return StorageType::CreateWritePortal(this->GetBuffers(), device, token);
  }
 
  VTKM_CONT WritePortalType PrepareForOutput(vtkm::Id numberOfValues,
                                             vtkm::cont::DeviceAdapterId device,
                                             vtkm::cont::Token& token) const
  {
    this->Allocate(numberOfValues, vtkm::CopyFlag::Off, token);
    return StorageType::CreateWritePortal(this->GetBuffers(), device, token);
  }
 
  VTKM_CONT bool IsOnDevice(vtkm::cont::DeviceAdapterId device) const
  {
    return detail::ArrayHandleIsOnDevice(this->Buffers, device);
  }
 
  VTKM_CONT bool IsOnHost() const
  {
    return this->IsOnDevice(vtkm::cont::DeviceAdapterTagUndefined{});
  }
 
  VTKM_CONT void SyncControlArray() const
  {
    // Creating a host read portal will force the data to be synced to the host.
    this->ReadPortal();
  }
 
  VTKM_CONT void Enqueue(const vtkm::cont::Token& token) const
  {
    for (auto&& buffer : this->Buffers)
    {
      buffer.Enqueue(token);
    }
  }
 
  VTKM_CONT void DeepCopyFrom(const vtkm::cont::ArrayHandle<ValueType, StorageTag>& source) const
  {
    VTKM_ASSERT(this->Buffers.size() == source.Buffers.size());
 
    for (std::size_t bufferIndex = 0; bufferIndex < this->Buffers.size(); ++bufferIndex)
    {
      this->Buffers[bufferIndex].DeepCopyFrom(source.Buffers[bufferIndex]);
    }
  }
 
  VTKM_CONT const std::vector<vtkm::cont::internal::Buffer>& GetBuffers() const
  {
    return this->Buffers;
  }
  VTKM_CONT std::vector<vtkm::cont::internal::Buffer>& GetBuffers() { return this->Buffers; }
 
private:
  mutable std::vector<vtkm::cont::internal::Buffer> Buffers;
 
protected:
  VTKM_CONT void SetBuffer(vtkm::IdComponent index, const vtkm::cont::internal::Buffer& buffer)
  {
    this->Buffers[static_cast<std::size_t>(index)] = buffer;
  }
 
  VTKM_CONT void SetBuffers(const std::vector<vtkm::cont::internal::Buffer>& buffers)
  {
    this->Buffers = buffers;
  }
  VTKM_CONT void SetBuffers(std::vector<vtkm::cont::internal::Buffer>&& buffers)
  {
    this->Buffers = std::move(buffers);
  }
};
 
namespace detail
{
 
template <typename T>
VTKM_NEVER_EXPORT VTKM_CONT inline void
printSummary_ArrayHandle_Value(const T& value, std::ostream& out, vtkm::VecTraitsTagSingleComponent)
{
  out << value;
}
 
VTKM_NEVER_EXPORT
VTKM_CONT
inline void printSummary_ArrayHandle_Value(vtkm::UInt8 value,
                                           std::ostream& out,
                                           vtkm::VecTraitsTagSingleComponent)
{
  out << static_cast<int>(value);
}
 
VTKM_NEVER_EXPORT
VTKM_CONT
inline void printSummary_ArrayHandle_Value(vtkm::Int8 value,
                                           std::ostream& out,
                                           vtkm::VecTraitsTagSingleComponent)
{
  out << static_cast<int>(value);
}
 
template <typename T>
VTKM_NEVER_EXPORT VTKM_CONT inline void printSummary_ArrayHandle_Value(
  const T& value,
  std::ostream& out,
  vtkm::VecTraitsTagMultipleComponents)
{
  using Traits = vtkm::internal::SafeVecTraits<T>;
  using ComponentType = typename Traits::ComponentType;
  using IsVecOfVec = typename vtkm::internal::SafeVecTraits<ComponentType>::HasMultipleComponents;
  vtkm::IdComponent numComponents = Traits::GetNumberOfComponents(value);
  out << "(";
  printSummary_ArrayHandle_Value(Traits::GetComponent(value, 0), out, IsVecOfVec());
  for (vtkm::IdComponent index = 1; index < numComponents; ++index)
  {
    out << ",";
    printSummary_ArrayHandle_Value(Traits::GetComponent(value, index), out, IsVecOfVec());
  }
  out << ")";
}
 
template <typename T1, typename T2>
VTKM_NEVER_EXPORT VTKM_CONT inline void printSummary_ArrayHandle_Value(
  const vtkm::Pair<T1, T2>& value,
  std::ostream& out,
  vtkm::VecTraitsTagSingleComponent)
{
  out << "{";
  printSummary_ArrayHandle_Value(
    value.first, out, typename vtkm::internal::SafeVecTraits<T1>::HasMultipleComponents());
  out << ",";
  printSummary_ArrayHandle_Value(
    value.second, out, typename vtkm::internal::SafeVecTraits<T2>::HasMultipleComponents());
  out << "}";
}
 
 
 
} // namespace detail
 
template <typename T, typename StorageT>
VTKM_NEVER_EXPORT VTKM_CONT inline void printSummary_ArrayHandle(
  const vtkm::cont::ArrayHandle<T, StorageT>& array,
  std::ostream& out,
  bool full = false)
{
  using ArrayType = vtkm::cont::ArrayHandle<T, StorageT>;
  using PortalType = typename ArrayType::ReadPortalType;
  using IsVec = typename vtkm::internal::SafeVecTraits<T>::HasMultipleComponents;
 
  vtkm::Id sz = array.GetNumberOfValues();
 
  out << "valueType=" << vtkm::cont::TypeToString<T>()
      << " storageType=" << vtkm::cont::TypeToString<StorageT>() << " " << sz
      << " values occupying " << (static_cast<size_t>(sz) * sizeof(T)) << " bytes [";
 
  PortalType portal = array.ReadPortal();
  if (full || sz <= 7)
  {
    for (vtkm::Id i = 0; i < sz; i++)
    {
      detail::printSummary_ArrayHandle_Value(portal.Get(i), out, IsVec());
      if (i != (sz - 1))
      {
        out << " ";
      }
    }
  }
  else
  {
    detail::printSummary_ArrayHandle_Value(portal.Get(0), out, IsVec());
    out << " ";
    detail::printSummary_ArrayHandle_Value(portal.Get(1), out, IsVec());
    out << " ";
    detail::printSummary_ArrayHandle_Value(portal.Get(2), out, IsVec());
    out << " ... ";
    detail::printSummary_ArrayHandle_Value(portal.Get(sz - 3), out, IsVec());
    out << " ";
    detail::printSummary_ArrayHandle_Value(portal.Get(sz - 2), out, IsVec());
    out << " ";
    detail::printSummary_ArrayHandle_Value(portal.Get(sz - 1), out, IsVec());
  }
  out << "]\n";
}
 
namespace internal
{
 
namespace detail
{
 
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>&);
template <typename T, typename S, typename... Args>
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                        const vtkm::cont::ArrayHandle<T, S>& array,
                                        const Args&... args);
template <typename... Args>
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                        const vtkm::cont::internal::Buffer& buffer,
                                        const Args&... args);
 
template <typename... Args>
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                        const std::vector<vtkm::cont::internal::Buffer>& addbuffs,
                                        const Args&... args);
template <typename Arg0, typename... Args>
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                        const Arg0& arg0,
                                        const Args&... args);
 
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>&)
{
  // Nothing left to add.
}
 
template <typename T, typename S, typename... Args>
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                        const vtkm::cont::ArrayHandle<T, S>& array,
                                        const Args&... args)
{
  CreateBuffersImpl(buffers, array.GetBuffers(), args...);
}
 
template <typename... Args>
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                        const vtkm::cont::internal::Buffer& buffer,
                                        const Args&... args)
{
  buffers.push_back(buffer);
  CreateBuffersImpl(buffers, args...);
}
 
template <typename... Args>
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                        const std::vector<vtkm::cont::internal::Buffer>& addbuffs,
                                        const Args&... args)
{
  buffers.insert(buffers.end(), addbuffs.begin(), addbuffs.end());
  CreateBuffersImpl(buffers, args...);
}
 
template <typename T, typename S, typename... Args>
VTKM_CONT inline void CreateBuffersResolveArrays(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                                 std::true_type,
                                                 const vtkm::cont::ArrayHandle<T, S>& array,
                                                 const Args&... args)
{
  CreateBuffersImpl(buffers, array, args...);
}
 
template <typename MetaData, typename... Args>
VTKM_CONT inline void CreateBuffersResolveArrays(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                                 std::false_type,
                                                 const MetaData& metadata,
                                                 const Args&... args)
{
  vtkm::cont::internal::Buffer buffer;
  buffer.SetMetaData(metadata);
  buffers.push_back(std::move(buffer));
  CreateBuffersImpl(buffers, args...);
}
 
template <typename Arg0, typename... Args>
VTKM_CONT inline void CreateBuffersImpl(std::vector<vtkm::cont::internal::Buffer>& buffers,
                                        const Arg0& arg0,
                                        const Args&... args)
{
  // If the argument is a subclass of ArrayHandle, the template resolution will pick this
  // overload instead of the correct ArrayHandle overload. To resolve that, check to see
  // if the type is an `ArrayHandle` and use `CreateBuffersResolveArrays` to choose the
  // right path.
  using IsArray = typename vtkm::cont::internal::ArrayHandleCheck<Arg0>::type::type;
  CreateBuffersResolveArrays(buffers, IsArray{}, arg0, args...);
}
 
} // namespace detail
 
template <typename... Args>
VTKM_CONT inline std::vector<vtkm::cont::internal::Buffer> CreateBuffers(const Args&... args)
{
  std::vector<vtkm::cont::internal::Buffer> buffers;
  buffers.reserve(sizeof...(args));
  detail::CreateBuffersImpl(buffers, args...);
  return buffers;
}
 
} // namespace internal
 
}
} //namespace vtkm::cont
 
#ifndef vtk_m_cont_ArrayHandleBasic_h
#include <vtkm/cont/ArrayHandleBasic.h>
#endif
 
#endif //vtk_m_cont_ArrayHandle_h