Class used by MFEM to store pointers to host and/or device memory. More...

#include <mem_manager.hpp>

Collaboration diagram for mfem::Memory< T >:

Public Member Functions
	Memory ()
	Default constructor: no initialization. More...

	Memory (const Memory &orig)=default
	Copy constructor: default. More...

	Memory (Memory &&orig)=default
	Move constructor: default. More...

Memory &	operator= (const Memory &orig)=default
	Copy-assignment operator: default. More...

Memory &	operator= (Memory &&orig)=default
	Move-assignment operator: default. More...

	Memory (int size)
	Allocate host memory for size entries. More...

	Memory (int size, MemoryType mt)
	Allocate memory for size entries with the given MemoryType mt. More...

	Memory (T *ptr, int size, bool own)
	Wrap an externally allocated host pointer, ptr with the current host memory type returned by MemoryManager::GetHostMemoryType(). More...

	Memory (T *ptr, int size, MemoryType mt, bool own)
	Wrap an externally allocated pointer, ptr, of the given MemoryType. More...

	Memory (const Memory &base, int offset, int size)
	Alias constructor. Create a Memory object that points inside the Memory object base. More...

	~Memory ()=default
	Destructor: default. More...

bool	OwnsHostPtr () const
	Return true if the host pointer is owned. Ownership indicates whether the pointer will be deleted by the method Delete(). More...

void	SetHostPtrOwner (bool own) const
	Set/clear the ownership flag for the host pointer. Ownership indicates whether the pointer will be deleted by the method Delete(). More...

bool	OwnsDevicePtr () const
	Return true if the device pointer is owned. Ownership indicates whether the pointer will be deleted by the method Delete(). More...

void	SetDevicePtrOwner (bool own) const
	Set/clear the ownership flag for the device pointer. Ownership indicates whether the pointer will be deleted by the method Delete(). More...

void	ClearOwnerFlags () const
	Clear the ownership flags for the host and device pointers, as well as any internal data allocated by the Memory object. More...

bool	UseDevice () const
	Read the internal device flag. More...

void	UseDevice (bool use_dev) const
	Set the internal device flag. More...

int	Capacity () const
	Return the size of the allocated memory. More...

void	Reset ()
	Reset the memory to be empty, ensuring that Delete() will be a no-op. More...

void	Reset (MemoryType host_mt)
	Reset the memory and set the host memory type. More...

bool	Empty () const
	Return true if the Memory object is empty, see Reset(). More...

void	New (int size)
	Allocate host memory for size entries with the current host memory type returned by MemoryManager::GetHostMemoryType(). More...

void	New (int size, MemoryType mt)
	Allocate memory for size entries with the given MemoryType. More...

void	Wrap (T *ptr, int size, bool own)
	Wrap an externally allocated host pointer, ptr with the current host memory type returned by MemoryManager::GetHostMemoryType(). More...

void	Wrap (T *ptr, int size, MemoryType mt, bool own)
	Wrap an externally allocated pointer, ptr, of the given MemoryType. More...

void	Wrap (T h_ptr, T d_ptr, int size, MemoryType h_mt, bool own)

void	MakeAlias (const Memory &base, int offset, int size)
	Create a memory object that points inside the memory object base. More...

void	Delete ()
	Delete the owned pointers. The Memory is not reset by this method, i.e. it will, generally, not be Empty() after this call. More...

T &	operator[] (int idx)
	Array subscript operator for host memory. More...

const T &	operator[] (int idx) const
	Array subscript operator for host memory, const version. More...

	operator T * ()
	Direct access to the host memory as T* (implicit conversion). More...

	operator const T * () const
	Direct access to the host memory as const T* (implicit conversion). More...

template<typename U >
	operator U * ()
	Direct access to the host memory via explicit typecast. More...

template<typename U >
	operator const U * () const
	Direct access to the host memory via explicit typecast, const version. More...

T *	ReadWrite (MemoryClass mc, int size)
	Get read-write access to the memory with the given MemoryClass. More...

const T *	Read (MemoryClass mc, int size) const
	Get read-only access to the memory with the given MemoryClass. More...

T *	Write (MemoryClass mc, int size)
	Get write-only access to the memory with the given MemoryClass. More...

void	Sync (const Memory &other) const
	Copy the host/device pointer validity flags from other to *this. More...

void	SyncAlias (const Memory &base, int alias_size) const
	Update the alias Memory this to match the memory location (all valid locations) of its base Memory, base*. More...

MemoryType	GetMemoryType () const
	Return a MemoryType that is currently valid. If both the host and the device pointers are currently valid, then the device memory type is returned. More...

void	CopyFrom (const Memory &src, int size)
	Copy size entries from src to *this. More...

void	CopyFromHost (const T *src, int size)
	Copy size entries from the host pointer src to *this. More...

void	CopyTo (Memory &dest, int size) const
	Copy size entries from this to dest*. More...

void	CopyToHost (T *dest, int size) const
	Copy size entries from this to the host pointer dest*. More...

void	PrintFlags () const
	Print the internal flags. More...

int	CompareHostAndDevice (int size) const
	If both the host and the device data are valid, compare their contents. More...

Protected Types
enum	FlagMask : unsigned { REGISTERED = 1 << 0, OWNS_HOST = 1 << 1, OWNS_DEVICE = 1 << 2, OWNS_INTERNAL = 1 << 3, VALID_HOST = 1 << 4, VALID_DEVICE = 1 << 5, USE_DEVICE = 1 << 6, ALIAS = 1 << 7 }

Protected Attributes
T *	h_ptr
	Pointer to host memory. Not owned. More...

int	capacity
	Size of the allocated memory. More...

MemoryType	h_mt
	Host memory type. More...

unsigned	flags
	Bit flags defined from the FlagMask enum. More...

Friends
class	MemoryManager

void	MemoryPrintFlags (unsigned flags)
	Print the state of a Memory object based on its internal flags. Useful in a debugger. See also Memory<T>::PrintFlags(). More...

Detailed Description

template<typename T>
class mfem::Memory< T >

Class used by MFEM to store pointers to host and/or device memory.

The template class parameter, T, must be a plain-old-data (POD) type.

In many respects this class behaves like a pointer: When destroyed, a Memory object does NOT automatically delete any allocated memory. Only the method Delete() will deallocate a Memory object. Other methods that modify the object (e.g. New(), Wrap(), etc) will simply overwrite the old contents. One difference with a pointer is that a const Memory object does not allow modification of the content (unlike e.g. a const pointer).

A Memory object stores up to two different pointers: one host pointer (with MemoryType from MemoryClass::HOST) and one device pointer (currently one of MemoryType: DEVICE, DEVICE_DEBUG, DEVICE_UMPIRE or MANAGED).

A Memory object can hold (wrap) an externally allocated pointer with any given MemoryType.

Access to the content of the Memory object can be requested with any given MemoryClass through the methods ReadWrite(), Read(), and Write(). Requesting such access may result in additional (internally handled) memory allocation and/or memory copy. When ReadWrite() is called, the returned pointer becomes the only valid pointer. When Read() is called, the returned pointer becomes valid, however the other pointer (host or device) may remain valid as well. When Write() is called, the returned pointer becomes the only valid pointer, however, unlike ReadWrite(), no memory copy will be performed.

The host memory (pointer from MemoryClass::HOST) can be accessed through the inline methods: operator[](), operator*(), the implicit conversion functions operator T*(), operator const T*(), and the explicit conversion template functions operator U*(), operator const U*() (with any suitable type U). In certain cases, using these methods may have undefined behavior, e.g. if the host pointer is not currently valid.

Definition at line 122 of file mem_manager.hpp.

Member Enumeration Documentation

template<typename T>

enum mfem::Memory::FlagMask : unsigned

protected

Enumerator
REGISTERED	The host pointer is registered with the MemoryManager
OWNS_HOST	The host pointer will be deleted by Delete()
OWNS_DEVICE	The device pointer will be deleted by Delete()
OWNS_INTERNAL	Ownership flag for internal Memory data.
VALID_HOST	Host pointer is valid.
VALID_DEVICE	Device pointer is valid
USE_DEVICE	Internal device flag, see e.g. Vector::UseDevice()
ALIAS	Pointer is an alias.

Definition at line 128 of file mem_manager.hpp.

Constructor & Destructor Documentation

template<typename T>

mfem::Memory< T >::Memory ( )

inline

Default constructor: no initialization.

Definition at line 155 of file mem_manager.hpp.

template<typename T>

mfem::Memory< T >::Memory ( const Memory< T > & orig )

default

Copy constructor: default.

template<typename T>

mfem::Memory< T >::Memory ( Memory< T > && orig )

default

Move constructor: default.

template<typename T>

mfem::Memory< T >::Memory ( int size )

inlineexplicit

Allocate host memory for size entries.

The allocation uses the current host memory type returned by MemoryManager::GetHostMemoryType().

Definition at line 172 of file mem_manager.hpp.

template<typename T>

mfem::Memory< T >::Memory	(	int	size,
		MemoryType	mt
	)

inline

Allocate memory for size entries with the given MemoryType mt.

The newly allocated memory is not initialized, however the given MemoryType is still set as valid.

Definition at line 178 of file mem_manager.hpp.

template<typename T>

mfem::Memory< T >::Memory	(	T *	ptr,
		int	size,
		bool	own
	)

inlineexplicit

Wrap an externally allocated host pointer, ptr with the current host memory type returned by MemoryManager::GetHostMemoryType().

The parameter own determines whether ptr will be deleted when the method Delete() is called.

Definition at line 184 of file mem_manager.hpp.

template<typename T>

mfem::Memory< T >::Memory	(	T *	ptr,
		int	size,
		MemoryType	mt,
		bool	own
	)

inline

Wrap an externally allocated pointer, ptr, of the given MemoryType.

The new memory object will have the given MemoryType set as valid.

The given ptr must be allocated appropriately for the given MemoryType.

The parameter own determines whether ptr will be deleted when the method Delete() is called.

Definition at line 194 of file mem_manager.hpp.

template<typename T>

mfem::Memory< T >::Memory	(	const Memory< T > &	base,
		int	offset,
		int	size
	)

inline

Alias constructor. Create a Memory object that points inside the Memory object base.

The new Memory object uses the same MemoryType(s) as base.

Definition at line 200 of file mem_manager.hpp.

template<typename T>

mfem::Memory< T >::~Memory ( )

default

Destructor: default.

Note: The destructor will NOT delete the current memory.

Member Function Documentation

template<typename T>

int mfem::Memory< T >::Capacity ( ) const

inline

Return the size of the allocated memory.

Definition at line 238 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::ClearOwnerFlags ( ) const

inline

Clear the ownership flags for the host and device pointers, as well as any internal data allocated by the Memory object.

Definition at line 227 of file mem_manager.hpp.

template<typename T >

int mfem::Memory< T >::CompareHostAndDevice ( int size ) const

inline

If both the host and the device data are valid, compare their contents.

This method can be useful for debugging. It is explicitly instantiated for Memory<T> with T = int and T = double.

Definition at line 976 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::CopyFrom	(	const Memory< T > &	src,
		int	size
	)

inline

Copy size entries from src to *this.

The given size should not exceed the Capacity() of the source src and the destination, *this.

Definition at line 908 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::CopyFromHost	(	const T *	src,
		int	size
	)

inline

Copy size entries from the host pointer src to *this.

The given size should not exceed the Capacity() of *this.

Definition at line 927 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::CopyTo	(	Memory< T > &	dest,
		int	size
	)		const

inline

Copy size entries from *this to dest.

The given size should not exceed the Capacity() of *this and the destination, dest.

Definition at line 423 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::CopyToHost	(	T *	dest,
		int	size
	)		const

inline

Copy size entries from *this to the host pointer dest.

The given size should not exceed the Capacity() of *this.

Definition at line 946 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::Delete ( )

inline

Delete the owned pointers. The Memory is not reset by this method, i.e. it will, generally, not be Empty() after this call.

Definition at line 774 of file mem_manager.hpp.

template<typename T>

bool mfem::Memory< T >::Empty ( ) const

inline

Return true if the Memory object is empty, see Reset().

Default-constructed objects are uninitialized, so they are not guaranteed to be empty.

Definition at line 253 of file mem_manager.hpp.

template<typename T >

MemoryType mfem::Memory< T >::GetMemoryType ( ) const

inline

Return a MemoryType that is currently valid. If both the host and the device pointers are currently valid, then the device memory type is returned.

Definition at line 901 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::MakeAlias	(	const Memory< T > &	base,
		int	offset,
		int	size
	)

inline

Create a memory object that points inside the memory object base.

The new Memory object uses the same MemoryType(s) as base.

Note: The current memory is NOT deleted by this method.

Definition at line 758 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::New ( int size )

inline

Allocate host memory for size entries with the current host memory type returned by MemoryManager::GetHostMemoryType().

Note: The current memory is NOT deleted by this method.

Definition at line 681 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::New	(	int	size,
		MemoryType	mt
	)

inline

Allocate memory for size entries with the given MemoryType.

The newly allocated memory is not initialized, however the given MemoryType is still set as valid.

Note: The current memory is NOT deleted by this method.

Definition at line 691 of file mem_manager.hpp.

template<typename T >

mfem::Memory< T >::operator const T * ( ) const

inline

Direct access to the host memory as const T* (implicit conversion).

This method can be used only if the host pointer is currently valid (the device pointer may be valid or invalid).

When the Memory is empty, this method can be used and it returns NULL.

Definition at line 813 of file mem_manager.hpp.

template<typename T >

template<typename U >

mfem::Memory< T >::operator const U * ( ) const

inlineexplicit

Direct access to the host memory via explicit typecast, const version.

A pointer to type T must be reinterpret_cast-able to a pointer to type const U.

This method can be used only if the host pointer is currently valid (the device pointer may be valid or invalid).

When the Memory is empty, this method can be used and it returns NULL.

Definition at line 830 of file mem_manager.hpp.

template<typename T >

mfem::Memory< T >::operator T * ( )

inline

Direct access to the host memory as T* (implicit conversion).

When the type T is const-qualified, this method can be used only if the host pointer is currently valid (the device pointer may be valid or invalid).

When the type T is not const-qualified, this method can be used only if the host pointer is the only valid pointer.

When the Memory is empty, this method can be used and it returns NULL.

Definition at line 803 of file mem_manager.hpp.

template<typename T >

template<typename U >

mfem::Memory< T >::operator U * ( )

inlineexplicit

Direct access to the host memory via explicit typecast.

A pointer to type T must be reinterpret_cast-able to a pointer to type U. In particular, this method cannot be used to cast away const-ness from the base type T.

When the type U is const-qualified, this method can be used only if the host pointer is currently valid (the device pointer may be valid or invalid).

When the type U is not const-qualified, this method can be used only if the host pointer is the only valid pointer.

When the Memory is empty, this method can be used and it returns NULL.

Definition at line 820 of file mem_manager.hpp.

template<typename T>

Memory& mfem::Memory< T >::operator= ( const Memory< T > & orig )

default

Copy-assignment operator: default.

template<typename T>

Memory& mfem::Memory< T >::operator= ( Memory< T > && orig )

default

Move-assignment operator: default.

template<typename T >

T & mfem::Memory< T >::operator[] ( int idx )

inline

Array subscript operator for host memory.

Definition at line 788 of file mem_manager.hpp.

template<typename T >

const T & mfem::Memory< T >::operator[] ( int idx ) const

inline

Array subscript operator for host memory, const version.

Definition at line 796 of file mem_manager.hpp.

template<typename T>

bool mfem::Memory< T >::OwnsDevicePtr ( ) const

inline

Return true if the device pointer is owned. Ownership indicates whether the pointer will be deleted by the method Delete().

Definition at line 218 of file mem_manager.hpp.

template<typename T>

bool mfem::Memory< T >::OwnsHostPtr ( ) const

inline

Return true if the host pointer is owned. Ownership indicates whether the pointer will be deleted by the method Delete().

Definition at line 209 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::PrintFlags ( ) const

inline

Print the internal flags.

This method can be useful for debugging. It is explicitly instantiated for Memory<T> with T = int and T = double.

Definition at line 970 of file mem_manager.hpp.

template<typename T >

const T * mfem::Memory< T >::Read	(	MemoryClass	mc,
		int	size
	)		const

inline

Get read-only access to the memory with the given MemoryClass.

The parameter size must not exceed the Capacity().

Definition at line 850 of file mem_manager.hpp.

template<typename T >

T * mfem::Memory< T >::ReadWrite	(	MemoryClass	mc,
		int	size
	)

inline

Get read-write access to the memory with the given MemoryClass.

If only read or only write access is needed, then the methods Read() or Write() should be used instead of this method.

The parameter size must not exceed the Capacity().

Definition at line 837 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::Reset ( )

inline

Reset the memory to be empty, ensuring that Delete() will be a no-op.

This is the Memory class equivalent to setting a pointer to NULL, see Empty().

Note: The current memory is NOT deleted by this method.

Definition at line 663 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::Reset ( MemoryType host_mt )

inline

Reset the memory and set the host memory type.

Definition at line 672 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::SetDevicePtrOwner ( bool own ) const

inline

Set/clear the ownership flag for the device pointer. Ownership indicates whether the pointer will be deleted by the method Delete().

Definition at line 222 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::SetHostPtrOwner ( bool own ) const

inline

Set/clear the ownership flag for the host pointer. Ownership indicates whether the pointer will be deleted by the method Delete().

Definition at line 213 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::Sync ( const Memory< T > & other ) const

inline

Copy the host/device pointer validity flags from other to *this.

This method synchronizes the pointer validity flags of two Memory objects that use the same host/device pointers, or when *this is an alias (sub-Memory) of other. Typically, this method should be called after other is manipulated in a way that changes its pointer validity flags (e.g. it was moved from device to host memory).

Definition at line 876 of file mem_manager.hpp.

template<typename T >

void mfem::Memory< T >::SyncAlias	(	const Memory< T > &	base,
		int	alias_size
	)		const

inline

Update the alias Memory *this to match the memory location (all valid locations) of its base Memory, base.

This method is useful when alias Memory is moved and manipulated in a different memory space. Such operations render the pointer validity flags of the base incorrect. Calling this method will ensure that base is up-to-date. Note that this is achieved by moving/copying *this (if necessary), and not base.

Definition at line 890 of file mem_manager.hpp.

template<typename T>

bool mfem::Memory< T >::UseDevice ( ) const

inline

Read the internal device flag.

Definition at line 231 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::UseDevice ( bool use_dev ) const

inline

Set the internal device flag.

Definition at line 234 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::Wrap	(	T *	ptr,
		int	size,
		bool	own
	)

inline

Wrap an externally allocated host pointer, ptr with the current host memory type returned by MemoryManager::GetHostMemoryType().

The parameter own determines whether ptr will be deleted when the method Delete() is called.

Note: The current memory is NOT deleted by this method.

Definition at line 704 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::Wrap	(	T *	ptr,
		int	size,
		MemoryType	mt,
		bool	own
	)

inline

Wrap an externally allocated pointer, ptr, of the given MemoryType.

The new memory object will have the given MemoryType set as valid.

The given ptr must be allocated appropriately for the given MemoryType.

The parameter own determines whether ptr will be deleted when the method Delete() is called.

Note: The current memory is NOT deleted by this method.

Definition at line 720 of file mem_manager.hpp.

template<typename T>

void mfem::Memory< T >::Wrap	(	T *	h_ptr,
		T *	d_ptr,
		int	size,
		MemoryType	h_mt,
		bool	own
	)

inline

Wrap an externally pair of allocated pointers, h_ptr and @ d_ptr, of the given host MemoryType h_mt. The new memory object will have the device MemoryType set as valid.

The given h_ptr and d_ptr must be allocated appropriately for the given host MemoryType and its associated device MemoryType:

MANAGED => MANAGED,
HOST_DEBUG => DEVICE_DEBUG,
HOST_UMPIRE => DEVICE_UMPIRE,
HOST, HOST_32, HOST_64 => DEVICE.

The parameter own determines whether both h_ptr and d_ptr will be deleted when the method Delete() is called.

Note

Ownership can also be controlled by using the following methods:

ClearOwnerFlags,
SetHostPtrOwner,
SetDevicePtrOwner.

The current memory is NOT deleted by this method.

Definition at line 745 of file mem_manager.hpp.

template<typename T >

T * mfem::Memory< T >::Write	(	MemoryClass	mc,
		int	size
	)

inline

Get write-only access to the memory with the given MemoryClass.

The parameter size must not exceed the Capacity().

The contents of the returned pointer is undefined, unless it was validated by a previous call to Read() or ReadWrite() with the same MemoryClass.

Definition at line 863 of file mem_manager.hpp.

Friends And Related Function Documentation

template<typename T>

friend class MemoryManager

friend

Definition at line 125 of file mem_manager.hpp.

template<typename T>

void MemoryPrintFlags ( unsigned flags )

friend

Print the state of a Memory object based on its internal flags. Useful in a debugger. See also Memory<T>::PrintFlags().

Definition at line 1361 of file mem_manager.cpp.

Member Data Documentation

template<typename T>

int mfem::Memory< T >::capacity

protected

Size of the allocated memory.

Definition at line 147 of file mem_manager.hpp.

template<typename T>

unsigned mfem::Memory< T >::flags

mutableprotected

Bit flags defined from the FlagMask enum.

Definition at line 149 of file mem_manager.hpp.

template<typename T>

MemoryType mfem::Memory< T >::h_mt

protected

Host memory type.

Definition at line 148 of file mem_manager.hpp.

template<typename T>

T* mfem::Memory< T >::h_ptr

protected

Pointer to host memory. Not owned.

The type of the pointer is given by the field h_mt; it can be any type from MemoryClass::HOST.

Definition at line 146 of file mem_manager.hpp.

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

general/mem_manager.hpp
general/mem_manager.cpp

Public Member Functions

Protected Types

Protected Attributes

Friends

Detailed Description

template<typename T> class mfem::Memory< T >

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

template<typename T>
class mfem::Memory< T >