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)

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

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

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

SpanConstT	operator[] (ItemRangeT ps) const
	Access a subset 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.

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

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

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


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

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


SpanT	operator[] (AllItemsT)

SpanConstT	operator[] (AllItemsT) const


size_type	size () const

bool	empty () const

pointer	data ()

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 TraitsT::type

using	SpanT = typename TraitsT::SpanT

using	SpanConstT = typename TraitsT::SpanConstT

using	pointer = detail::ContainerObserverPtr< SpanT, M >

using	const_pointer = detail::ContainerObserverPtr< SpanConstT, M >

using	reference = typename SpanT::reference

using	const_reference = typename SpanConstT::reference

using	size_type = MakeSize_t< I >

using	ItemIdT = I

using	ItemRangeT = Range< ItemIdT >

using	AllItemsT = detail::AllItems_t< T, M >

using	reference_type = reference

using	const_reference_type = const_reference

	Collection ()=default

	Collection (Collection const &)=default

	Collection (Collection &&)=default

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. (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 both host and device. Unified addressing must be supported by the current device, or an exception will be thrown when initializing the collection. Memory pages will reside on in "pinned" memory on host, and each access from device code to a changed page will require a slow memory transfer. Allocating pinned memory is slow and reduces the memory available to the system: so only allocate the smallest amount needed with the longest possible lifetime. Frequently accessing data from device code will result in low performance. Use case for mapped memory are:

as a source or destination memory space for asynchronous operations,
on integrated GPU architecture, or
a single coalesced read or write from device code.

Accessing a const_reference collection in device memory will return a wrapper container that accesses the low-level data through the celeritas::ldg wrapper function, which can accelerate random access on GPU by telling the compiler the memory will not be changed during the lifetime of the kernel. Therefore it is important to only use const Collections for shared, immutable-after-creation "params" data.

Accessing a reference collection returns mutable pointers, even when given the collection as a const reference.

Since the behavior of this class does not depend on the item ID (only the types do), the implementation of each function directly forwards to a less-templated function to reduce object size.

Member Typedef Documentation

◆ AllItemsT

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

using celeritas::Collection< T, W, M, I >::AllItemsT = detail::AllItems_t<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 = detail::ContainerObserverPtr<SpanConstT, M>

Default constructors

◆ const_reference

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

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

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 = const_reference

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 = detail::ContainerObserverPtr<SpanT, M>

Default constructors

◆ reference

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

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

Default constructors

◆ reference_type

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

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

Default constructors

◆ size_type

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

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

Default constructors

◆ SpanConstT

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

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

Default constructors

◆ SpanT

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

using celeritas::Collection< T, W, M, I >::SpanT = typename TraitsT::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 TraitsT::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. Allowable transformations and memory moves are statically checked.

◆ 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. Allowable transformations and memory moves are statically checked.

Member Function Documentation

◆ data() [1/2]

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

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

inline

Direct accessors to underlying data

◆ data() [2/2]

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

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

inline

Direct accessors to underlying data

◆ empty()

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

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

inline

Direct accessors 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. Allowable transformations and memory moves are statically checked.

◆ 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. Allowable transformations and memory moves are statically checked.

◆ operator[]() [1/2]

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

SpanT celeritas::Collection< T, W, M, I >::operator[] ( AllItemsT )

inline

Access all data as a span (memspace-safe)

◆ operator[]() [2/2]

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

SpanConstT celeritas::Collection< T, W, M, I >::operator[] ( AllItemsT ) const

inline

Access all data as a span (memspace-safe)

◆ size()

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

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

inline

Direct accessors 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

Member Typedef Documentation

◆ AllItemsT

◆ const_pointer

◆ const_reference

◆ const_reference_type

◆ ItemIdT

◆ ItemRangeT

◆ pointer

◆ reference

◆ 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]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ size()