Containers

A set of array containers to manage device, host and pinned memory.

class GPUcontainer

Interface of containers of device (GPU) data.

Subclassed by mirheo::DeviceBuffer< BelongingTags >, mirheo::DeviceBuffer< char >, mirheo::DeviceBuffer< int >, mirheo::DeviceBuffer< int2 >, mirheo::DeviceBuffer< mirheo::Force >, mirheo::DeviceBuffer< mirheo::MapEntry >, mirheo::DeviceBuffer< mirheo::TemplRigidMotion >, mirheo::DeviceBuffer< real >, mirheo::DeviceBuffer< real4 >, mirheo::DeviceBuffer< T >, mirheo::PinnedBuffer< T >, mirheo::PinnedBuffer< bool >, mirheo::PinnedBuffer< ChannelType >, mirheo::PinnedBuffer< char >, mirheo::PinnedBuffer< CudaVarPtr >, mirheo::PinnedBuffer< double >, mirheo::PinnedBuffer< double3 >, mirheo::PinnedBuffer< int >, mirheo::PinnedBuffer< int2 >, mirheo::PinnedBuffer< int3 >, mirheo::PinnedBuffer< mirheo::Force >, mirheo::PinnedBuffer< mirheo::ParticleCheckerPlugin::Status >, mirheo::PinnedBuffer< msd_plugin::ReductionType >, mirheo::PinnedBuffer< rdf_plugin::CountType >, mirheo::PinnedBuffer< real *>, mirheo::PinnedBuffer< real >, mirheo::PinnedBuffer< real3 >, mirheo::PinnedBuffer< real4 >, mirheo::PinnedBuffer< rmacf_plugin::ReductionType >, mirheo::PinnedBuffer< size_t >, mirheo::PinnedBuffer< stats_plugin::ReductionType >, mirheo::PinnedBuffer< unsigned long long int >, mirheo::PinnedBuffer< vacf_plugin::ReductionType >, mirheo::PinnedBuffer< virial_pressure_plugin::ReductionType >

Public Functions

virtual size_t size() const = 0

Return

number of stored elements

virtual size_t datatype_size() const = 0

Return

the size (in bytes) of a single element

virtual void *genericDevPtr() const = 0

Return

pointer to device data

virtual void resize_anew(size_t n) = 0

resize the internal array.

No guarantee to keep the current data.

Parameters

• n: New size (in number of elements). Must be non negative.

virtual void resize(size_t n, cudaStream_t stream) = 0

resize the internal array.

Keeps the current data.

Parameters

• n: New size (in number of elements). Must be non negative.
• stream: Used to copy the data internally

virtual void clearDevice(cudaStream_t stream) = 0

Call cudaMemset on the array.

Parameters

• stream: Execution stream

virtual GPUcontainer *produce() const = 0

Create a new instance of the concrete container implementation.

template <typename T>
class DeviceBuffer : public mirheo::GPUcontainer

Data only on the device (GPU)

Never releases any memory, keeps a buffer big enough to store maximum number of elements it ever held (except in the destructor).

Template Parameters

• T: The type of a single element to store.

Public Functions

DeviceBuffer(size_t n = 0)

Construct a DeviceBuffer of given size.

Parameters

• n: The initial number of elements

DeviceBuffer(const DeviceBuffer &b)

Copy constructor.

DeviceBuffer &operator=(const DeviceBuffer &b)

Assignment operator.

DeviceBuffer(DeviceBuffer &&b)

Move constructor; To enable std::swap()

DeviceBuffer &operator=(DeviceBuffer &&b)

Move assignment; To enable std::swap()

size_t datatype_size() const

Return

the size (in bytes) of a single element

size_t size() const

Return

number of stored elements

void *genericDevPtr() const

Return

pointer to device data

void resize(size_t n, cudaStream_t stream)

resize the internal array.

Keeps the current data.

Parameters

• n: New size (in number of elements). Must be non negative.
• stream: Used to copy the data internally

void resize_anew(size_t n)

resize the internal array.

No guarantee to keep the current data.

Parameters

• n: New size (in number of elements). Must be non negative.

GPUcontainer *produce() const

Create a new instance of the concrete container implementation.

T *devPtr() const

Return

device pointer to data

void clearDevice(cudaStream_t stream)

Call cudaMemset on the array.

Parameters

• stream: Execution stream

void clear(cudaStream_t stream)

clear the device data

template <typename Cont>
auto copy(const Cont &cont, cudaStream_t stream)

Copy data from another container of the same template type.

Can only copy from another DeviceBuffer of HostBuffer, but not PinnedBuffer.

Template Parameters

• Cont: The source container type. Must have the same data type than the current instance.

Parameters

• cont: The source container
• stream: Execution stream

auto copy(const DeviceBuffer<T> &cont)

synchronous copy

void copyFromDevice(const PinnedBuffer<T> &cont, cudaStream_t stream)

Copy the device data of a PinnedBuffer to the internal buffer.

Note

The copy is performed asynchronously. The user must manually synchronize with the stream if needed.

Parameters

• cont: the source container
• stream: The stream used to copy the data.

void copyFromHost(const PinnedBuffer<T> &cont, cudaStream_t stream)

Copy the host data of a PinnedBuffer to the internal buffer.

Note

The copy is performed asynchronously. The user must manually synchronize with the stream if needed.

Parameters

• cont: the source container
• stream: The stream used to copy the data.

template <typename T>
class HostBuffer

Data only on the host.

The data is allocated as pinned memory using the CUDA utilities. This allows to transfer asynchronously data from the device (e.g. DeviceBuffer).

Never releases any memory, keeps a buffer big enough to store maximum number of elements it ever held (except in the destructor).

Template Parameters

• T: The type of a single element to store.

Public Functions

HostBuffer(size_t n = 0)

construct a HostBuffer with a given size

Parameters

• n: The initial number of elements

HostBuffer(const HostBuffer &b)

copy constructor.

HostBuffer &operator=(const HostBuffer &b)

Assignment operator.

HostBuffer(HostBuffer &&b)

Move constructor; To enable std::swap()

HostBuffer &operator=(HostBuffer &&b)

Move assignment; To enable std::swap()

size_t datatype_size() const

Return

the size of a single element (in bytes)

size_t size() const

Return

the number of elements

T *hostPtr() const

Return

pointer to host memory

T *data() const

For uniformity with std::vector.

T &operator[](size_t i)

Return

element with given index

const T &operator[](size_t i) const

Return

element with given index

void resize(size_t n)

resize the internal array.

Keeps the current data.

Parameters

• n: New size (in number of elements). Must be non negative.

void resize_anew(size_t n)

resize the internal array.

No guarantee to keep the current data.

Parameters

• n: New size (in number of elements). Must be non negative.

T *begin()

To support range-based loops.

T *end()

To support range-based loops.

const T *begin() const

To support range-based loops.

const T *end() const

To support range-based loops.

void clear()

Set all the bytes to 0.

template <typename Cont>
auto copy(const Cont &cont)

Copy data from a HostBuffer of the same template type.

template <typename Cont>
auto copy(const Cont &cont, cudaStream_t stream)

Copy data from a DeviceBuffer of the same template type.

void genericCopy(const GPUcontainer *cont, cudaStream_t stream)

Copy data from an arbitrary GPUcontainer.

Note

the type sizes must be compatible (equal or multiple of each other)

Parameters

• cont: a pointer to the source container.
• stream: Stream used to copy the data.

template <typename T>
class PinnedBuffer : public mirheo::GPUcontainer

Device data with mirror host data.

Useful to transfer arrays between host and device memory.

The host data is allocated as pinned memory using the CUDA utilities. This allows to transfer asynchronously data from the device.

Never releases any memory, keeps a buffer big enough to store maximum number of elements it ever held (except in the destructor).

Note

Host and device data are not automatically synchronized! Use downloadFromDevice() and uploadToDevice() MANUALLY to sync

Template Parameters

• T: The type of a single element to store.

Public Functions

PinnedBuffer(size_t n = 0)

Construct a PinnedBuffer with given number of elements.

Parameters

• n: initial number of elements. Must be non negative.

PinnedBuffer(const PinnedBuffer &b)

Copy constructor.

PinnedBuffer &operator=(const PinnedBuffer &b)

assignment operator

PinnedBuffer(PinnedBuffer &&b)

Move constructor; To enable std::swap()

PinnedBuffer &operator=(PinnedBuffer &&b)

Move assignment; To enable std::swap()

size_t datatype_size() const

Return

the size (in bytes) of a single element

size_t size() const

Return

number of stored elements

void *genericDevPtr() const

Return

pointer to device data

void resize(size_t n, cudaStream_t stream)

resize the internal array.

Keeps the current data.

Parameters

• n: New size (in number of elements). Must be non negative.
• stream: Used to copy the data internally

void resize_anew(size_t n)

resize the internal array.

No guarantee to keep the current data.

Parameters

• n: New size (in number of elements). Must be non negative.

GPUcontainer *produce() const

Create a new instance of the concrete container implementation.

T *hostPtr() const

Return

pointer to host data

T *data() const

For uniformity with std::vector.

T *devPtr() const

Return

pointer to device data

T &operator[](size_t i)

allow array-like bracketed access to HOST data

const T &operator[](size_t i) const

allow array-like bracketed access to HOST data

T *begin()

To support range-based loops.

T *end()

To support range-based loops.

const T *begin() const

To support range-based loops.

const T *end() const

To support range-based loops.

void downloadFromDevice(cudaStream_t stream, ContainersSynch synch = ContainersSynch::Synch)

Copy internal data from device to host.

Parameters

• stream: The stream used to perform the copy
• synch: Synchronicity of the operation. If synchronous, the call will block until the operation is done.

void uploadToDevice(cudaStream_t stream)

Copy the internal data from host to device.

Parameters

• stream: The stream used to perform the copy

void clear(cudaStream_t stream)

Set all the bytes to 0 on both host and device.

void clearDevice(cudaStream_t stream)

Set all the bytes to 0 on device only.

void clearHost()

Set all the bytes to 0 on host only.

void copy(const DeviceBuffer<T> &cont, cudaStream_t stream)

Copy data from a DeviceBuffer of the same template type.

void copy(const HostBuffer<T> &cont)

Copy data from a HostBuffer of the same template type.

void copy(const PinnedBuffer<T> &cont, cudaStream_t stream)

Copy data from a PinnedBuffer of the same template type.

void copyDeviceOnly(const PinnedBuffer<T> &cont, cudaStream_t stream)

Copy data from device pointer of a PinnedBuffer of the same template type.

void copy(const PinnedBuffer<T> &cont)

synchronous copy