MFEM  v4.0
Finite element discretization library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
Public Member Functions | Protected Types | Protected Attributes | Friends | List of all members
mfem::Memory< T > Class Template Reference

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

#include <mem_manager.hpp>

Collaboration diagram for mfem::Memory< T >:
[legend]

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...
 
Memoryoperator= (const Memory &orig)=default
 Copy-assignment operator: default. More...
 
Memoryoperator= (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 type MemoryType::HOST. 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...
 
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 type MemoryType::HOST. 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 type MemoryType::HOST. More...
 
void Wrap (T *ptr, int size, MemoryType mt, bool own)
 Wrap an externally allocated pointer, ptr, of the given MemoryType. More...
 
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. 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...
 

Protected Types

enum  FlagMask {
  REGISTERED = 1, OWNS_HOST = 2, OWNS_DEVICE = 4, OWNS_INTERNAL = 8,
  VALID_HOST = 16, VALID_DEVICE = 32, ALIAS = 64, USE_DEVICE = 128
}
 

Protected Attributes

T * h_ptr
 Pointer to host memory. Not owned. More...
 
int capacity
 
unsigned flags
 

Friends

class MemoryManager
 
void MemoryPrintFlags (unsigned flags)
 Print the state of a Memory object based on its internal flags. Useful in a debugger. 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::CUDA or MemoryTyep::CUDA_UVM).

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 102 of file mem_manager.hpp.

Member Enumeration Documentation

template<typename T>
enum mfem::Memory::FlagMask
protected
Enumerator
REGISTERED 

h_ptr 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.

ALIAS 
USE_DEVICE 

Internal device flag, see e.g. Vector::UseDevice()

Definition at line 108 of file mem_manager.hpp.

Constructor & Destructor Documentation

template<typename T>
mfem::Memory< T >::Memory ( )
inline

Default constructor: no initialization.

Definition at line 133 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.

Definition at line 148 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 154 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 type MemoryType::HOST.

The parameter own determines whether ptr will be deleted (using operator delete[]) when the method Delete() is called.

Definition at line 160 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 170 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 176 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 214 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 203 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 673 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 692 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 374 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 711 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.

Definition at line 542 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 226 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 666 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 526 of file mem_manager.hpp.

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

Allocate host memory for size entries with type MemoryType::HOST.

Note
The current memory is NOT deleted by this method.

Definition at line 230 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 491 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 577 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 594 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 567 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 584 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 552 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 560 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 194 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 185 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 614 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 601 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 221 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 198 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 189 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 641 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 655 of file mem_manager.hpp.

template<typename T>
bool mfem::Memory< T >::UseDevice ( ) const
inline

Read the internal device flag.

Definition at line 207 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 210 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 type MemoryType::HOST.

The parameter own determines whether ptr will be deleted (using operator delete[]) when the method Delete() is called.

Note
The current memory is NOT deleted by this method.

Definition at line 246 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 508 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 628 of file mem_manager.hpp.

Friends And Related Function Documentation

template<typename T>
friend class MemoryManager
friend

Definition at line 105 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.

Definition at line 693 of file mem_manager.cpp.

Member Data Documentation

template<typename T>
int mfem::Memory< T >::capacity
protected

Definition at line 126 of file mem_manager.hpp.

template<typename T>
unsigned mfem::Memory< T >::flags
mutableprotected

Definition at line 127 of file mem_manager.hpp.

template<typename T>
T* mfem::Memory< T >::h_ptr
protected

Pointer to host memory. Not owned.

When the pointer is not registered with the MemoryManager, this pointer has type MemoryType::HOST. When the pointer is registered, it can be any type from MemoryClass::HOST.

Definition at line 125 of file mem_manager.hpp.


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