stormm::structure::Hybrid< T > Class Template Reference

An evolution of GpuBuffer in pmemd.cuda, the Composite array has elements that are accessible from either the GPU or the CPU. In unified mode, the two data are one insofar as the programmer sees it, and the page migration engine engaged by cudaMallocManaged handles the two physical memory spaces at a very low level. In other modes, composite memory must be uploaded or downloaded explicitly in order to maintain synchrony between host and device memory spaces. This struct mimics a lot of the most noteworthy behavior of std::vector, but with the potential to behave as a pointer as well. In this manner, it is intended to confer the convenience of C++ with the freedom of classic C programming. More...

#include <hybrid.h>

Public Member Functions
	Hybrid (const Hybrid &original)
	Copy constructor handles the reassignment of the underlying raw pointers.
	Hybrid (Hybrid &&original)
	The move constructor handles migration of a Hybrid object.
	~Hybrid ()
	Destructor frees data with no re-allocation.
Hybrid &	operator= (const Hybrid &other)
	Copy assignment constructor handles the reassignment of the underlying raw pointers.
Hybrid &	operator= (Hybrid &&other)
	The move assignment operator must likewise handle transfer of the underlying data.
HybridKind	getKind () const
	Get the object kind (pointer or array)
HybridFormat	getFormat () const
	Get the memory format.
size_t	size () const
	Return the number of elements in the Hybrid object's data array(s)
size_t	capacity () const
	Return the number of elements in the Hybrid object's data array(s)
size_t	getPointerIndex () const
	Return the pointer start position, targeting another ARRAY-kind Hybrid object (relevant for POINTER-kind Hybrid objects only)
size_t	getElementSize () const
	Return the size of an individual element in the data array(s)
HybridLabel	getLabel () const
	Return the object's identifying label.
int	getSerialNumber () const
	Return the object's identifying serial number.
int	getAllocations () const
	Return the number of times this object has been allocated.
int	getTargetSerialNumber () const
	Produce the serial number of the target (only valid for POINTER-kind objects). This function is needed for the copy constructor in the POINTER-kind case.
bool	verifyTarget () const
	Verify that the target of a HybridKind::POINTER object remains in the state it was in when the pointer was first set.
void	shrinkToFit ()
	Trim a Hybrid array to the exact size of its data.
void	setPointer (Hybrid< T > *target, size_t position=0, llint new_length=-1LL)
	Set a Hybrid pointer struct to a segment of a Hybrid array struct.
void	swapTarget (Hybrid< T > *new_target, ExceptionResponse policy=ExceptionResponse::SILENT)
	Swap the target of a POINTER-kind Hybrid object, transferring its starting index and current length to apply instead to the new target. Bounds checks will still be applied. Not valid for ARRAY-kind Hybrid objects or for POINTER-kind objects that have no current target.
	Hybrid (size_t length_in=0, const char *tag_in=nullptr, const HybridFormat format_in=default_hpc_format, const HybridKind kind_in=HybridKind::ARRAY)
	Constructors vary based on whether CUDA is part of the compilation.
	Hybrid (const std::vector< T > &S_in, const char *tag_in=nullptr, const HybridFormat format_in=default_hpc_format)
	Hybrid (const HybridKind kind_in, const char *tag_in=nullptr, const HybridFormat format_in=default_hpc_format, size_t length_in=0)
const T *	data (const HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get a pointer directly to the GpuArray's data on either the host or the device.
T *	data (const HybridTargetLevel tier=HybridTargetLevel::HOST)
T	readHost (size_t index) const
	Get data from a given index of the host_data array. This substitutes for direct array access via the [ ] operator, as the host_data and devc_data pointers are private.
std::vector< T >	readHost (size_t offset, size_t count) const
std::vector< T >	readHost () const
void	readHost (T *v, size_t offset, size_t count) const
void	putHost (const T value, size_t index)
	Put data into the host_data array. This substitutes for direct array access via the [ ] operator, as the host_data and devc_data pointers are private.
void	putHost (const std::vector< T > &values, size_t offset, size_t count)
void	putHost (const std::vector< T > &values)
size_t	putHost (Hybrid< T > *target, const std::vector< T > &values, size_t offset=0, size_t padding=0, size_t count=0)
void	pushBack (const T element)
	Mimic the C++ std::vector push_back functionality. A bounds check is followed by extension of the data arrays in the current format if necessary. The new element is placed at the end of the host_data array. The Hybrid object must be ARRAY-kind or a POINTER-kind with sufficient maximum capacity (no reallocation needed). Additions will go to the CPU host memory.
void	pushBack (const T *elements, const size_t element_count)
void	pushBack (const std::vector< T > &elements)
void	pushBack (const Hybrid< T > &elements)
void	resize (size_t new_length)
	A std::vector-like resize() feature.
void	resize (size_t new_length, T value)
const Hybrid< T >	getPointer (size_t position=0, size_t new_length=0, const char *tag_in=nullptr) const
	Get a pointer to a Hybrid object at a specific location. This is the way to get const Hybrid POINTER-kind objects to const ARRAY-kind Hybrid objects. This function is only available to ARRAY-kind Hybrid objects.
Hybrid< T >	getPointer (size_t position=0, size_t new_length=0, const char *tag_in=nullptr)

Detailed Description

template<typename T>
class stormm::structure::Hybrid< T >

An evolution of GpuBuffer in pmemd.cuda, the Composite array has elements that are accessible from either the GPU or the CPU. In unified mode, the two data are one insofar as the programmer sees it, and the page migration engine engaged by cudaMallocManaged handles the two physical memory spaces at a very low level. In other modes, composite memory must be uploaded or downloaded explicitly in order to maintain synchrony between host and device memory spaces. This struct mimics a lot of the most noteworthy behavior of std::vector, but with the potential to behave as a pointer as well. In this manner, it is intended to confer the convenience of C++ with the freedom of classic C programming.

Constructor & Destructor Documentation

Hybrid() [1/3]

template<typename T>

stormm::card::Hybrid< T >::Hybrid ( size_t length_in = 0, const char * tag_in = nullptr, const HybridFormat format_in = default_hpc_format, const HybridKind kind_in = HybridKind::ARRAY )

explicit

Constructors vary based on whether CUDA is part of the compilation.

Overloaded:

• Simple constructor takes an optional size and an optional format
• Secondary constructor takes a std::vector of the intended type and allocates based on its size, again with an optional format

Parameters

length_in	The input length of the array
tag_in	A human-readable tag by which to call this array
format_in	Format of the resulting hybrid data structure
kind_in	The kind of Hybrid object this will be

Hybrid() [2/3]

template<typename T>

stormm::card::Hybrid< T >::Hybrid

(

const Hybrid< T > &

original

)

Copy constructor handles the reassignment of the underlying raw pointers.

Parameters

original

The Hybrid object to copy

Hybrid() [3/3]

template<typename T>

stormm::card::Hybrid< T >::Hybrid

(

Hybrid< T > &&

original

)

The move constructor handles migration of a Hybrid object.

Parameters

original

The Hybrid object to move

Member Function Documentation

data()

template<typename T>

const T * stormm::card::Hybrid< T >::data

(

const HybridTargetLevel

tier = HybridTargetLevel::HOST

)

const

Get a pointer directly to the GpuArray's data on either the host or the device.

Overloaded:

• Get a const pointer if the object is const
• Get a pointer that can modify the underlying data if the object is non-const

Parameters

tier	The level at which to set the pointer

getPointer()

template<typename T>

const Hybrid< T > stormm::card::Hybrid< T >::getPointer	(	size_t	position = 0,
		size_t	new_length = 0,
		const char *	tag_in = nullptr ) const

Get a pointer to a Hybrid object at a specific location. This is the way to get const Hybrid POINTER-kind objects to const ARRAY-kind Hybrid objects. This function is only available to ARRAY-kind Hybrid objects.

Overloaded:

• Get a const Hybrid POINTER-kind object to a const Hybrid array
• Get a non-const Hybrid POINTER-kind object to a non-const array

Parameters

position	The position in the array to which the POINTER-kind Hybrid object targets
new_length	The length that the POINTER-kind Hybrid object will have (default 0 implies it will be the length of the current array minus the POINTER-kind object's starting position)

operator=() [1/2]

template<typename T>

Hybrid & stormm::card::Hybrid< T >::operator=

(

const Hybrid< T > &

other

)

Copy assignment constructor handles the reassignment of the underlying raw pointers.

Parameters

other

The Hybrid object to copy (a different name for a better semantic fit in the context of the = sign)

operator=() [2/2]

template<typename T>

Hybrid & stormm::card::Hybrid< T >::operator=

(

Hybrid< T > &&

other

)

The move assignment operator must likewise handle transfer of the underlying data.

Parameters

other

The Hybrid object to move (a different name for a better semantic fit in the context of the = sign)

pushBack()

template<typename T>

void stormm::card::Hybrid< T >::pushBack

(

const T

element

)

Mimic the C++ std::vector push_back functionality. A bounds check is followed by extension of the data arrays in the current format if necessary. The new element is placed at the end of the host_data array. The Hybrid object must be ARRAY-kind or a POINTER-kind with sufficient maximum capacity (no reallocation needed). Additions will go to the CPU host memory.

Overloaded:

• Add a single element
• Add multiple elements from a C-style array, Standard Template Library vector, or another Hybrid object.

Parameters

element	The new item to add
elements	An array of new elements to add
element_count	The trusted length of elements, if adding from a C-style array

putHost()

template<typename T>

void stormm::card::Hybrid< T >::putHost	(	const T	value,
		size_t	index )

Put data into the host_data array. This substitutes for direct array access via the [ ] operator, as the host_data and devc_data pointers are private.

Overloaded:

• Put a single element into the host_data at a specific index
• Put an array of elements into the host_data, starting at a specific offset index
• Target this (POINTER-kind) Hybrid object to another (ARRAY-kind) Hybrid object at a specific offset, then load this object's host_data with an array of elements and pad additional space in the target with zeros. Return the next unpadded index in the target for convenience.

Parameters

value	The data to write into host_data
values	The data to write into host_data
target	Another Hybrid object to target
index	The index of host_data to write
offset	The index at which to begin writing values into host_data
count	If the data comes as an array, write only the first count values into the Hybrid object's host_data. The default of zero implies that the entirety of values shall be written.

readHost()

template<typename T>

T stormm::card::Hybrid< T >::readHost

(

size_t

index

)

const

Get data from a given index of the host_data array. This substitutes for direct array access via the [ ] operator, as the host_data and devc_data pointers are private.

Overloaded:

• Read a single element
• Read a subset of the elements, starting at an arbitrary point in the host_data array
• Read the entire host_data array, up to its length, into a new (out-of-place) array
• Read data into a pre-allocated, trusted array

Parameters

index	Index of the host_data array to read
offset	Starting index of the host_data array to read
count	The number of elements to access and return

resize()

template<typename T>

void stormm::card::Hybrid< T >::resize

(

size_t

new_length

)

A std::vector-like resize() feature.

Overloaded:

• Resize and fill the new space with zero
• Resize and fill the new space with a constant value

Parameters

new_length	The new length. If less than the current length, all that will change is the counted number of elements. The original data will persist, as will the array(s) storing it.
new_value	The value with which to populate new space.

setPointer()

template<typename T>

void stormm::card::Hybrid< T >::setPointer	(	Hybrid< T > *	target,
		size_t	position = 0,
		llint	new_length = -1LL )

Set a Hybrid pointer struct to a segment of a Hybrid array struct.

Parameters

target	Pointer to the Hybrid object to point into. This is a pointer because otherwise it would have to be a non-const reference.
position	The location in target where this Hybrid pointer shall direct its own data array(s)
new_length	The new, maximum length of data that this pointer shall occupy. If left unset or set to a negative value, it will default to the remaining elements of the Hybrid array struct as it is currently found (target.size() - position). The pointer's maximum capacity will likewise be set to new_length, or if new_length is not set it will default to (target.capacity() - position).

swapTarget()

template<typename T>

void stormm::card::Hybrid< T >::swapTarget	(	Hybrid< T > *	new_target,
		ExceptionResponse	policy = ExceptionResponse::SILENT )

Swap the target of a POINTER-kind Hybrid object, transferring its starting index and current length to apply instead to the new target. Bounds checks will still be applied. Not valid for ARRAY-kind Hybrid objects or for POINTER-kind objects that have no current target.

Parameters

target	Pointer to the new Hybrid object to point into. This is a pointer because otherwise it would have to be a non-const reference.
policy	Indicate different actions to take if the Hybrid object does not yet point to any target.

---

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

• src/Accelerator/hybrid.h