ryujin::MirroredStorage< Derived > Class Template Reference

#include <source/gpu.h>

Inheritance diagram for ryujin::MirroredStorage< Derived >:

Public Member Functions
Memory space access and synchronization
template<typename MemorySpace >
bool	is_resident () const
template<typename MemorySpace >
bool	is_pinned () const
template<typename MemorySpace >
void	copy_to_memory_space () const
template<typename MemorySpace >
void	move_to_memory_space ()
TransferPolicy	transfer_policy () const
void	set_transfer_policy (const TransferPolicy transfer_policy)

Protected Member Functions
Internal methods used by derived classes
	MirroredStorage ()=default
template<typename MemorySpace >
void	prepare_read_access () const
template<typename MemorySpace >
void	prepare_write_access ()
void	reset_residency (const bool host_resident, const bool default_resident)

Detailed Description

template<typename Derived>
class ryujin::MirroredStorage< Derived >

A CRTP base class that manages the residency state of data mirrored between the host and default (device) memory spaces. It provides a unified interface for querying residency (is_resident()) and for transferring data between memory spaces (copy_to_memory_space() and move_to_memory_space()) that is used by the SparsityPattern, SparseMatrix, and MultiComponentVector classes.

Data can be resident on either memory space, or on both (after a copy_to_memory_space() operation).

The Derived class must provide the following (private) primitives and declare friend class MirroredStorage<Derived>;:

template <typename MemorySpace> void allocate_storage() const;
template <typename To, typename From> void deep_copy_storage() const;
template <typename MemorySpace> void deallocate_storage();

allocate_storage() and deep_copy_storage() must be const and may only modify mutable members: they are reachable from a const view() under an implicit transfer policy.

Note

Under an implicit transfer policy a const object mutates internal (mutable) state when a view is requested for a non-resident memory space. Concurrent access is thus not thread safe.

move_to_memory_space() invalidates all references and pointers to data on the memory space we move away from. This invalidates any existing View on that memory space. Managing view lifetime is the caller's responsibility.

if host and device memory spaces coincide, then the following special rules apply: the residency flags for host and default space must coincide: is_resident<>() always returns true for a properly initialized object. is_pinned<>() always returns false. move_to_memory_space<>() and copy_to_memory_space<>() assert that both memory spaces are resident and simply return.

A memory space pinned by the current transfer policy has to be resident, see is_pinned(). The Derived class thus has to initialize an object in the following order: first put the data in place, then call reset_residency(), and only then select the transfer policy with set_transfer_policy().

Definition at line 194 of file gpu.h.

Constructor & Destructor Documentation

MirroredStorage()

template<typename Derived >

ryujin::MirroredStorage< Derived >::MirroredStorage ( )

protecteddefault

Member Function Documentation

is_resident()

template<typename Derived >

template<typename MemorySpace >

bool ryujin::MirroredStorage< Derived >::is_resident

(

)

const

Returns true if data is available on the selected memory space, i.e., if view<MemorySpace>() may be called. Both memory spaces can be resident simultaneously. If the host and default memory spaces coincide the function returns true for both memory spaces (once the object has been initialized).

is_pinned()

template<typename Derived >

template<typename MemorySpace >

bool ryujin::MirroredStorage< Derived >::is_pinned

(

)

const

Returns true if the selected memory space is "pinned" by the current transfer policy, i.e., if the data has to remain resident on it and all operations that would deallocate its storage - a move_to_memory_space() to the other memory space and a writable view on the other memory space - are disallowed.

The function always returns false if the host and default memory spaces coincide.

copy_to_memory_space()

template<typename Derived >

template<typename MemorySpace >

void ryujin::MirroredStorage< Derived >::copy_to_memory_space

(

)

const

Make a deep copy of the data to the selected memory space. Both memory spaces remain valid/resident.

Note

The copy is skipped if the selected memory space is already resident. No consistency check is performed, whether both memory spaces hold the same data.

move_to_memory_space()

template<typename Derived >

template<typename MemorySpace >

void ryujin::MirroredStorage< Derived >::move_to_memory_space

(

)

Move the data to the selected memory space, then deallocate the storage of the other memory space and mark it non-resident.

Note

The copy is skipped if the selected memory space is already resident. No consistency check is performed, whether both memory spaces hold the same data.

The operation is disallowed if the other memory space is pinned by the current transfer policy, see is_pinned().

transfer_policy()

template<typename Derived >

TransferPolicy ryujin::MirroredStorage< Derived >::transfer_policy

(

)

const

Return the currently selected transfer policy.

set_transfer_policy()

template<typename Derived >

void ryujin::MirroredStorage< Derived >::set_transfer_policy

(

const TransferPolicy

transfer_policy

)

Select a transfer policy, see the documentation of TransferPolicy.

Note

The function asserts that a memory space pinned by the selected policy is resident. Transfer the data to the memory space that is about to be pinned prior to calling this function.

prepare_read_access()

template<typename Derived >

template<typename MemorySpace >

void ryujin::MirroredStorage< Derived >::prepare_read_access ( ) const

protected

Prepare read access on the selected memory space.

This function is called by the derived class at the beginning of every (const) view() method returning a read-only view: Under an implicit transfer policy the function performs an implicit copy_to_memory_space(), otherwise it asserts that the selected memory space is resident.

prepare_write_access()

template<typename Derived >

template<typename MemorySpace >

void ryujin::MirroredStorage< Derived >::prepare_write_access ( )

protected

Prepare write access on the selected memory space.

This function is called by the derived class at the beginning of every view() method returning a writable view: Under an implicit transfer policy the function performs an implicit move_to_memory_space() (invalidating a stale mirror on the other memory space), otherwise it asserts that the selected memory space is resident. The operation is disallowed if the other memory space is pinned by the current transfer policy, see is_pinned().

reset_residency()

template<typename Derived >

void ryujin::MirroredStorage< Derived >::reset_residency ( const bool  host_resident, const bool  default_resident  )

protected

Reset the residency flags. This function is called by the derived class at the end of reinit(), prior to selecting the transfer policy with set_transfer_policy().

Note

If the host and default memory spaces coincide both flags have to coincide as well. The function further asserts that a memory space pinned by the current transfer policy remains resident.

---

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

• source/gpu.h