Manage generic array-like data ownership and transfer from host to device. More...

#include <Collection.hh>

Public Member Functions
template<Ownership W2, MemSpace M2>
Collection &	operator= (Collection< T, W2, M2, I > const &other)

template<Ownership W2, MemSpace M2>
Collection &	operator= (Collection< T, W2, M2, I > &other)

CELER_FORCEINLINE_FUNCTION reference_type	operator[] (ItemIdT i)
	Access a single element.

CELER_FORCEINLINE_FUNCTION const_reference_type	operator[] (ItemIdT i) const
	Access a single element (const).

CELER_FORCEINLINE_FUNCTION SpanT	operator[] (ItemRangeT ps)
	Access a subset of the data as a Span.

CELER_FORCEINLINE_FUNCTION SpanConstT	operator[] (ItemRangeT ps) const
	Access a subset of the data as a Span (const).

CELER_FORCEINLINE_FUNCTION SpanT	operator[] (AllItemsT)
	Access all of the data as a Span.

CELER_FORCEINLINE_FUNCTION SpanConstT	operator[] (AllItemsT) const
	Access all of the data as a Span (const).


template<Ownership W2, MemSpace M2>
	Collection (Collection< T, W2, M2, I > const &other)
	Construct or assign from another collection. More...

template<Ownership W2, MemSpace M2>
	Collection (Collection< T, W2, M2, I > &other)
	Construct or assign from another collection. More...

template<Ownership W2, MemSpace M2>
Collection< T, W, M, I > &	operator= (Collection< T, W2, M2, I > const &other)
	Construct or assign from another collection. More...

template<Ownership W2, MemSpace M2>
Collection< T, W, M, I > &	operator= (Collection< T, W2, M2, I > &other)
	Construct or assign from another collection. More...


Collection &	operator= (Collection const &other)=default

Collection &	operator= (Collection &&other)=default


CELER_FORCEINLINE_FUNCTION size_type	size () const

CELER_FORCEINLINE_FUNCTION bool	empty () const

CELER_FORCEINLINE_FUNCTION pointer	data ()

CELER_FORCEINLINE_FUNCTION const_pointer	data () const

Static Public Attributes
static constexpr Ownership	ownership = W

static constexpr MemSpace	memspace = M

Friends
template<class T2 , MemSpace M2, class Id2 >
class	CollectionBuilder

template<class T2 , class Id2 >
class	DedupeCollectionBuilder

Type aliases
using	value_type = typename CollectionTraitsT::type

using	SpanT = typename CollectionTraitsT::SpanT

using	SpanConstT = typename CollectionTraitsT::SpanConstT

using	pointer = ObserverPtr< value_type, M >

using	const_pointer = ObserverPtr< const_value_type, M >

using	reference_type = typename CollectionTraitsT::reference_type

using	const_reference_type = typename CollectionTraitsT::const_reference_type

using	size_type = typename I::size_type

using	ItemIdT = I

using	ItemRangeT = Range< ItemIdT >

using	AllItemsT = AllItems< T, M >

	Collection ()=default

	Collection (Collection const &)=default

	Collection (Collection &&)=default

using	StorageT = typename detail::CollectionStorage< T, W, M >::type

CELER_FORCEINLINE_FUNCTION StorageT const &	storage () const

CELER_FORCEINLINE_FUNCTION StorageT &	storage ()

Detailed Description

template<class T, Ownership W, MemSpace M, class I = ItemId<T>>
class celeritas::Collection< T, W, M, I >

Manage generic array-like data ownership and transfer from host to device.

Data are constructed incrementally on the host, then copied (along with their associated ItemRange) to device. A Collection can act as a std::vector<T>, DeviceVector<T>, Span<T>, or Span<const T>. The Spans can point to host or device memory, but the MemSpace template argument protects against accidental accesses from the wrong memory space.

Each Collection object is usually accessed with an ItemRange, which references a contiguous set of elements in the Collection. For example, setup code on the host would extend the Collection with a series of vectors, the addition of which returns a ItemRange that returns the equivalent data on host or device. This methodology allows complex nested data structures to be built up quickly at setup time without knowing the size requirements beforehand.

Host-device functions and classes should use Collection with a reference or const_reference Ownership, and the MemSpace::native type, which expects device memory when compiled inside a CUDA file and host memory when used inside a C++ source or test. (This design choice prevents a single CUDA file from compiling separate host-compatible and device-compatible compute kernels, but in the case of Celeritas this situation won't arise, because we always want to build host code in C++ files for development ease and to allow testing when CUDA is disabled.)

A MemSpace::Mapped collection will be accessible on the host and the device. Unified addressing must be supported by the current device or an exception will be thrown when using the collection. Mapped pinned memory (i.e. zero-copy memory) is allocated, pages will always reside on host memory and each access from device code will require a slow memory transfer. Allocating pinned memory is slow and reduce the memory available to the system: only allocate the smallest amount needed with the longest possible lifetime. Frequently accessing data from device code will result in low performance. Usecase for this MemSapce are: as a src / dst memory space for asynchronous operations, on integrated GPU architecture, or a single coalesced read or write from device code. https://docs.nvidia.com/cuda/cuda-c-best-practices-guide/index.html#zero-copy

Accessing a const_reference collection in device memory will return a wrapper container that accesses the low-level data through the __ldg primitive, which can accelerate random access by telling the compiler the memory will not be changed during the lifetime of the kernel. Therefore it is important to only use Collections for shared, constant "params" data.

Member Typedef Documentation

◆ AllItemsT

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::AllItemsT = AllItems<T, M>

Default constructors

◆ const_pointer

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::const_pointer = ObserverPtr<const_value_type, M>

Default constructors

◆ const_reference_type

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::const_reference_type = typename CollectionTraitsT::const_reference_type

Default constructors

◆ ItemIdT

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::ItemIdT = I

Default constructors

◆ ItemRangeT

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::ItemRangeT = Range<ItemIdT>

Default constructors

◆ pointer

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::pointer = ObserverPtr<value_type, M>

Default constructors

◆ reference_type

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::reference_type = typename CollectionTraitsT::reference_type

Default constructors

◆ size_type

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::size_type = typename I::size_type

Default constructors

◆ SpanConstT

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::SpanConstT = typename CollectionTraitsT::SpanConstT

Default constructors

◆ SpanT

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::SpanT = typename CollectionTraitsT::SpanT

Default constructors

◆ value_type

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

using celeritas::Collection< T, W, M, I >::value_type = typename CollectionTraitsT::type

Default constructors

Constructor & Destructor Documentation

◆ Collection() [1/5]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

celeritas::Collection< T, W, M, I >::Collection ( )

default

Default constructors

◆ Collection() [2/5]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

celeritas::Collection< T, W, M, I >::Collection ( Collection< T, W, M, I > const & )

default

Default constructors

◆ Collection() [3/5]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

celeritas::Collection< T, W, M, I >::Collection ( Collection< T, W, M, I > && )

default

Default constructors

◆ Collection() [4/5]

template<class T , Ownership W, MemSpace M, class I >

template<Ownership W2, MemSpace M2>

celeritas::Collection< T, W, M, I >::Collection ( Collection< T, W2, M2, I > const & other )

inlineexplicit

Construct or assign from another collection.

These are generally used to create "references" to "values" (same memory space) but can also be used to copy from device to host. The detail::CollectionAssigner class statically checks for allowable transformations and memory moves.

TODO: add optimization to do an in-place copy (rather than a new allocation) if the host and destination are the same size.

◆ Collection() [5/5]

template<class T , Ownership W, MemSpace M, class I >

template<Ownership W2, MemSpace M2>

celeritas::Collection< T, W, M, I >::Collection ( Collection< T, W2, M2, I > & other )

inlineexplicit

Construct or assign from another collection.

These are generally used to create "references" to "values" (same memory space) but can also be used to copy from device to host. The detail::CollectionAssigner class statically checks for allowable transformations and memory moves.

TODO: add optimization to do an in-place copy (rather than a new allocation) if the host and destination are the same size.

Member Function Documentation

◆ data() [1/2]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

CELER_FORCEINLINE_FUNCTION pointer celeritas::Collection< T, W, M, I >::data ( )

inline

Direct accesors to underlying data

◆ data() [2/2]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

CELER_FORCEINLINE_FUNCTION const_pointer celeritas::Collection< T, W, M, I >::data ( ) const

inline

Direct accesors to underlying data

◆ empty()

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

CELER_FORCEINLINE_FUNCTION bool celeritas::Collection< T, W, M, I >::empty ( ) const

inline

Direct accesors to underlying data

◆ operator=() [1/4]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

Collection& celeritas::Collection< T, W, M, I >::operator= ( Collection< T, W, M, I > && other )

default

Default assignment

◆ operator=() [2/4]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

Collection& celeritas::Collection< T, W, M, I >::operator= ( Collection< T, W, M, I > const & other )

default

Default assignment

◆ operator=() [3/4]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

template<Ownership W2, MemSpace M2>

Collection<T, W, M, I>& celeritas::Collection< T, W, M, I >::operator= ( Collection< T, W2, M2, I > & other )

Construct or assign from another collection.

These are generally used to create "references" to "values" (same memory space) but can also be used to copy from device to host. The detail::CollectionAssigner class statically checks for allowable transformations and memory moves.

TODO: add optimization to do an in-place copy (rather than a new allocation) if the host and destination are the same size.

◆ operator=() [4/4]

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

template<Ownership W2, MemSpace M2>

Collection<T, W, M, I>& celeritas::Collection< T, W, M, I >::operator= ( Collection< T, W2, M2, I > const & other )

Construct or assign from another collection.

These are generally used to create "references" to "values" (same memory space) but can also be used to copy from device to host. The detail::CollectionAssigner class statically checks for allowable transformations and memory moves.

TODO: add optimization to do an in-place copy (rather than a new allocation) if the host and destination are the same size.

◆ size()

template<class T , Ownership W, MemSpace M, class I = ItemId<T>>

CELER_FORCEINLINE_FUNCTION size_type celeritas::Collection< T, W, M, I >::size ( ) const

inline

Direct accesors to underlying data

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

Collection.hh

Public Member Functions

Static Public Attributes

Friends

Type aliases

Detailed Description

template<class T, Ownership W, MemSpace M, class I = ItemId<T>> class celeritas::Collection< T, W, M, I >

Member Typedef Documentation

◆ AllItemsT

◆ const_pointer

◆ const_reference_type

◆ ItemIdT

◆ ItemRangeT

◆ pointer

◆ reference_type

◆ size_type

◆ SpanConstT

◆ SpanT

◆ value_type

Constructor & Destructor Documentation

◆ Collection() [1/5]

◆ Collection() [2/5]

◆ Collection() [3/5]

◆ Collection() [4/5]

◆ Collection() [5/5]

Member Function Documentation

◆ data() [1/2]

◆ data() [2/2]

◆ empty()

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ size()

template<class T, Ownership W, MemSpace M, class I = ItemId<T>>
class celeritas::Collection< T, W, M, I >