2014-02-10 19:53:03 +00:00
|
|
|
//============================================================================
|
|
|
|
// 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.
|
|
|
|
//
|
|
|
|
// Copyright 2014 Sandia Corporation.
|
|
|
|
// Copyright 2014 UT-Battelle, LLC.
|
2015-05-21 12:09:22 +00:00
|
|
|
// Copyright 2014 Los Alamos National Security.
|
2014-02-10 19:53:03 +00:00
|
|
|
//
|
|
|
|
// Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
|
|
|
|
// the U.S. Government retains certain rights in this software.
|
|
|
|
//
|
|
|
|
// Under the terms of Contract DE-AC52-06NA25396 with Los Alamos National
|
|
|
|
// Laboratory (LANL), the U.S. Government retains certain rights in
|
|
|
|
// this software.
|
|
|
|
//============================================================================
|
2014-06-23 23:33:04 +00:00
|
|
|
#ifndef vtk_m_cont_Storage_h
|
|
|
|
#define vtk_m_cont_Storage_h
|
2014-02-10 19:53:03 +00:00
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#define VTKM_STORAGE_ERROR -2
|
|
|
|
#define VTKM_STORAGE_UNDEFINED -1
|
|
|
|
#define VTKM_STORAGE_BASIC 1
|
2014-02-10 19:53:03 +00:00
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#ifndef VTKM_STORAGE
|
|
|
|
#define VTKM_STORAGE VTKM_STORAGE_BASIC
|
2014-02-10 19:53:03 +00:00
|
|
|
#endif
|
|
|
|
|
2015-09-17 19:45:35 +00:00
|
|
|
#include <vtkm/StaticAssert.h>
|
2016-12-16 22:04:58 +00:00
|
|
|
|
|
|
|
#include <vtkm/cont/vtkm_cont_export.h>
|
2015-09-17 19:45:35 +00:00
|
|
|
#include <vtkm/internal/ExportMacros.h>
|
2014-04-03 20:08:53 +00:00
|
|
|
|
2014-02-10 19:53:03 +00:00
|
|
|
namespace vtkm {
|
|
|
|
namespace cont {
|
|
|
|
|
|
|
|
#ifdef VTKM_DOXYGEN_ONLY
|
|
|
|
/// \brief A tag specifying client memory allocation.
|
|
|
|
///
|
2014-06-23 23:33:04 +00:00
|
|
|
/// A Storage tag specifies how an ArrayHandle allocates and frees memory. The
|
|
|
|
/// tag StorageTag___ does not actually exist. Rather, this documentation is
|
|
|
|
/// provided to describe how array storage objects are specified. Loading the
|
|
|
|
/// vtkm/cont/Storage.h header will set a default array storage. You can
|
|
|
|
/// specify the default storage by first setting the VTKM_STORAGE macro.
|
|
|
|
/// Currently it can only be set to VTKM_STORAGE_BASIC.
|
2014-02-10 19:53:03 +00:00
|
|
|
///
|
2014-06-23 23:33:04 +00:00
|
|
|
/// User code external to VTK-m is free to make its own StorageTag. This is a
|
|
|
|
/// good way to get VTK-m to read data directly in and out of arrays from other
|
|
|
|
/// libraries. However, care should be taken when creating a Storage. One
|
|
|
|
/// particular problem that is likely is a storage that "constructs" all the
|
|
|
|
/// items in the array. If done incorrectly, then memory of the array can be
|
|
|
|
/// incorrectly bound to the wrong processor. If you do provide your own
|
|
|
|
/// StorageTag, please be diligent in comparing its performance to the
|
|
|
|
/// StorageTagBasic.
|
2014-02-10 19:53:03 +00:00
|
|
|
///
|
2014-06-23 23:33:04 +00:00
|
|
|
/// To implement your own StorageTag, you first must create a tag class (an
|
2016-12-16 21:51:04 +00:00
|
|
|
/// empty struct) defining your tag (i.e. struct VTKM_ALWAYS_EXPORT StorageTagMyAlloc { };). Then
|
2014-06-23 23:33:04 +00:00
|
|
|
/// provide a partial template specialization of vtkm::cont::internal::Storage
|
|
|
|
/// for your new tag.
|
2014-02-10 19:53:03 +00:00
|
|
|
///
|
2016-12-16 21:51:04 +00:00
|
|
|
struct VTKM_ALWAYS_EXPORT StorageTag___ { };
|
2014-02-10 19:53:03 +00:00
|
|
|
#endif // VTKM_DOXYGEN_ONLY
|
|
|
|
|
|
|
|
namespace internal {
|
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
struct UndefinedStorage { };
|
2014-04-03 20:08:53 +00:00
|
|
|
|
|
|
|
namespace detail {
|
|
|
|
|
|
|
|
// This class should never be used. It is used as a placeholder for undefined
|
2014-06-23 23:33:04 +00:00
|
|
|
// Storage objects. If you get a compiler error involving this object, then it
|
|
|
|
// probably comes from trying to use an ArrayHandle with bad template
|
|
|
|
// arguments.
|
2014-04-03 20:08:53 +00:00
|
|
|
template<typename T>
|
|
|
|
struct UndefinedArrayPortal {
|
2015-09-17 19:45:35 +00:00
|
|
|
VTKM_STATIC_ASSERT(sizeof(T) == static_cast<size_t>(-1));
|
2014-04-03 20:08:53 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
} // namespace detail
|
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
/// This templated class must be partially specialized for each StorageTag
|
|
|
|
/// created, which will define the implementation for that tag.
|
2014-02-10 19:53:03 +00:00
|
|
|
///
|
2014-06-23 23:33:04 +00:00
|
|
|
template<typename T, class StorageTag>
|
|
|
|
class Storage
|
2014-04-03 20:08:53 +00:00
|
|
|
#ifndef VTKM_DOXYGEN_ONLY
|
2014-06-23 23:33:04 +00:00
|
|
|
: public vtkm::cont::internal::UndefinedStorage
|
2014-04-03 20:08:53 +00:00
|
|
|
{
|
|
|
|
public:
|
|
|
|
typedef vtkm::cont::internal::detail::UndefinedArrayPortal<T> PortalType;
|
|
|
|
typedef vtkm::cont::internal::detail::UndefinedArrayPortal<T> PortalConstType;
|
|
|
|
};
|
|
|
|
#else //VTKM_DOXYGEN_ONLY
|
2014-02-10 19:53:03 +00:00
|
|
|
{
|
|
|
|
public:
|
|
|
|
|
|
|
|
/// The type of each item in the array.
|
|
|
|
///
|
|
|
|
typedef T ValueType;
|
|
|
|
|
|
|
|
/// \brief The type of portal objects for the array.
|
|
|
|
///
|
|
|
|
/// The actual portal object can take any form. This is a simple example of a
|
|
|
|
/// portal to a C array.
|
|
|
|
///
|
|
|
|
typedef ::vtkm::cont::internal::ArrayPortalFromIterators<ValueType*> PortalType;
|
|
|
|
|
|
|
|
/// \brief The type of portal objects (const version) for the array.
|
|
|
|
///
|
|
|
|
/// The actual portal object can take any form. This is a simple example of a
|
|
|
|
/// portal to a C array.
|
|
|
|
///
|
|
|
|
typedef ::vtkm::cont::internal::ArrayPortalFromIterators<const ValueType*> PortalConstType;
|
|
|
|
|
|
|
|
/// Returns a portal to the array.
|
|
|
|
///
|
2016-10-19 22:42:58 +00:00
|
|
|
VTKM_CONT
|
2014-02-10 19:53:03 +00:00
|
|
|
PortalType GetPortal();
|
|
|
|
|
|
|
|
/// Returns a portal to the array with immutable values.
|
|
|
|
///
|
2016-10-19 22:42:58 +00:00
|
|
|
VTKM_CONT
|
2014-02-10 19:53:03 +00:00
|
|
|
PortalConstType GetPortalConst() const;
|
|
|
|
|
|
|
|
/// Retuns the number of entries allocated in the array.
|
2016-10-19 22:42:58 +00:00
|
|
|
VTKM_CONT
|
2014-02-10 19:53:03 +00:00
|
|
|
vtkm::Id GetNumberOfValues() const;
|
|
|
|
|
|
|
|
/// \brief 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
|
2017-01-09 21:15:32 +00:00
|
|
|
/// ErrorBadAllocation if the array cannot be allocated or
|
|
|
|
/// ErrorBadValue if the allocation is not feasible (for example, the
|
2015-02-10 22:58:41 +00:00
|
|
|
/// array storage is read-only).
|
2014-02-10 19:53:03 +00:00
|
|
|
///
|
2016-10-19 22:42:58 +00:00
|
|
|
VTKM_CONT
|
2014-02-10 19:53:03 +00:00
|
|
|
void Allocate(vtkm::Id numberOfValues);
|
|
|
|
|
|
|
|
/// \brief 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 \c numberOfValues. The data
|
|
|
|
/// in the array (from indices 0 to \c numberOfValues - 1) are the same, but
|
|
|
|
/// \c 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.
|
2016-10-19 22:42:58 +00:00
|
|
|
VTKM_CONT
|
2014-02-10 19:53:03 +00:00
|
|
|
void Shrink(vtkm::Id numberOfValues);
|
|
|
|
|
|
|
|
/// \brief Frees any resources (i.e. memory) stored in this array.
|
|
|
|
///
|
2014-09-08 20:59:11 +00:00
|
|
|
/// After calling this method GetNumberOfValues will return 0. The
|
2014-06-23 23:33:04 +00:00
|
|
|
/// resources should also be released when the Storage class is
|
2014-02-10 19:53:03 +00:00
|
|
|
/// destroyed.
|
2016-10-19 22:42:58 +00:00
|
|
|
VTKM_CONT
|
2014-02-10 19:53:03 +00:00
|
|
|
void ReleaseResources();
|
|
|
|
};
|
|
|
|
#endif // VTKM_DOXYGEN_ONLY
|
|
|
|
|
|
|
|
} // namespace internal
|
|
|
|
|
|
|
|
}
|
|
|
|
} // namespace vtkm::cont
|
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
// This is put at the bottom of the header so that the Storage template is
|
|
|
|
// declared before any implementations are called.
|
2014-02-10 19:53:03 +00:00
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#if VTKM_STORAGE == VTKM_STORAGE_BASIC
|
2014-02-10 19:53:03 +00:00
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#include <vtkm/cont/StorageBasic.h>
|
|
|
|
#define VTKM_DEFAULT_STORAGE_TAG ::vtkm::cont::StorageTagBasic
|
2014-02-10 19:53:03 +00:00
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#elif VTKM_STORAGE == VTKM_STORAGE_ERROR
|
2014-02-10 19:53:03 +00:00
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#include <vtkm/cont/internal/StorageError.h>
|
|
|
|
#define VTKM_DEFAULT_STORAGE_TAG ::vtkm::cont::internal::StorageTagError
|
2014-02-10 19:53:03 +00:00
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#elif (VTKM_STORAGE == VTKM_STORAGE_UNDEFINED) || !defined(VTKM_STORAGE)
|
2014-02-10 19:53:03 +00:00
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#ifndef VTKM_DEFAULT_STORAGE_TAG
|
|
|
|
#warning If array storage is undefined, VTKM_DEFAULT_STORAGE_TAG must be defined.
|
2014-02-10 19:53:03 +00:00
|
|
|
#endif
|
|
|
|
|
|
|
|
#endif
|
|
|
|
|
2014-06-23 23:33:04 +00:00
|
|
|
#endif //vtk_m_cont_Storage_h
|