amrex::Arena Class Reference

Abstract base class for memory arenas. More...

#include <AMReX_Arena.H>

Inheritance diagram for amrex::Arena:

Public Member Functions
virtual	~Arena ()=default
	Arena () noexcept=default
	Arena (const Arena &rhs)=delete
	Arena (Arena &&rhs)=delete
Arena &	operator= (const Arena &rhs)=delete
Arena &	operator= (Arena &&rhs)=delete
virtual void *	alloc (std::size_t sz)=0
	Allocate sz bytes from this arena.
virtual std::pair< void *, std::size_t >	alloc_in_place (void *pt, std::size_t szmin, std::size_t szmax)
	Allocate memory in-place if possible.
virtual void *	shrink_in_place (void *pt, std::size_t sz)
	Shrink allocation size in-place.
virtual void	free (void *pt)=0
	Free a previously allocated block pointed to by pt.
virtual std::size_t	freeUnused ()
	Release unused cached memory back to the system.
virtual std::size_t	largestFreeBlock () const
	Return the largest free memory block already held by this Arena.
virtual bool	isDeviceAccessible () const
virtual bool	isHostAccessible () const
virtual bool	isManaged () const
	Check whether it is managed GPU memory.
virtual bool	isDevice () const
	Check whether it is non-managed GPU device memory.
virtual bool	isPinned () const
	Check whether it is pinned host memory.
virtual bool	hasFreeDeviceMemory (std::size_t sz)
	Does the device have enough free memory for allocating this much memory? For CPU builds, this always return true. This is not a const function because it may attempt to release memory back to the system.
void	registerForProfiling (const std::string &memory_name)
	Add this Arena to the list of Arenas that are profiled by TinyProfiler.
void	deregisterFromProfiling ()
	Remove this Arena from the list of Arenas that are profiled by TinyProfiler. This is equivalent to destructing and re-constructing the Arena.
virtual bool	isStreamOrderedArena () const
	Is this GPU stream ordered memory allocator?
virtual void	streamOrderedFree (void *pt, gpuStream_t stream)
const ArenaInfo &	arenaInfo () const
	Return the ArenaInfo object for querying.
virtual void	ResetMaxUsageCounter ()

Static Public Member Functions
static std::size_t	align (std::size_t sz)
	Return the smallest multiple of Arena::align_size that is >= sz bytes.
static void	Initialize (bool minimal)
	Initialize the Arena subsystem (used internally by AMReX).
static void	PrintUsage (bool print_max_usage=false)
	Print memory usage information of all arenas.
static void	PrintUsageToStream (std::ostream &os, std::string const &space)
	Print memory usage information of all arenas to a given output stream.
static void	PrintUsageToFiles (std::string const &filename, std::string const &message)
	Print memory usage information of all arenas to given file.
static void	Finalize ()
	Used internally by amrex.
static bool	IsInitialized ()

Static Public Attributes
static const std::size_t	align_size = 256

Protected Member Functions
virtual std::size_t	freeUnused_protected ()
void *	allocate_system (std::size_t nbytes)
void	deallocate_system (void *p, std::size_t nbytes)

Static Protected Member Functions
static void	out_of_memory_abort (std::string const &memory_type, std::size_t nbytes, std::string const &error_msg)

Protected Attributes
ArenaInfo	arena_info

Detailed Description

Abstract base class for memory arenas.

Subclasses manage a pool of memory (CPU, GPU device, managed, or pinned) and expose alloc()/free() for raw byte allocation and deallocation.

Constructor & Destructor Documentation

~Arena()

virtual amrex::Arena::~Arena ( )

virtualdefault

Arena() [1/3]

amrex::Arena::Arena ( )

defaultnoexcept

Arena() [2/3]

amrex::Arena::Arena ( const Arena &  rhs )

delete

Arena() [3/3]

amrex::Arena::Arena ( Arena &&  rhs )

delete

Member Function Documentation

align()

std::size_t amrex::Arena::align ( std::size_t  sz )

static

Return the smallest multiple of Arena::align_size that is >= sz bytes.

alloc()

virtual void * amrex::Arena::alloc ( std::size_t  sz )

pure virtual

Allocate sz bytes from this arena.

Parameters

sz	Number of bytes to allocate.

Returns

Pointer to the allocated memory.

Implemented in amrex::CArena, amrex::PArena, amrex::BArena, and amrex::SArena.

alloc_in_place()

virtual std::pair< void *, std::size_t > amrex::Arena::alloc_in_place ( void *  pt, std::size_t  szmin, std::size_t  szmax  )

inlinevirtual

Allocate memory in-place if possible.

In this implementation of the virtual function, a new allocation is always performed, and it returns the new pointer and allocation size. Note that this function does NOT free the existing allocation. So it's the caller's responsibility to free the original pointer when appropriate.

Parameters

pt	Existing allocation to be reused when possible.
szmin	Minimum acceptable size for reusing pt in place.
szmax	Requested size for the returned allocation.

Returns

Pointer/size pair describing the resulting allocation.

Reimplemented in amrex::CArena.

allocate_system()

void * amrex::Arena::allocate_system ( std::size_t  nbytes )

protected

arenaInfo()

const ArenaInfo & amrex::Arena::arenaInfo ( ) const

inline

Return the ArenaInfo object for querying.

deallocate_system()

void amrex::Arena::deallocate_system ( void *  p, std::size_t  nbytes  )

protected

deregisterFromProfiling()

void amrex::Arena::deregisterFromProfiling

(

)

Remove this Arena from the list of Arenas that are profiled by TinyProfiler. This is equivalent to destructing and re-constructing the Arena.

Finalize()

void amrex::Arena::Finalize ( )

static

Used internally by amrex.

free()

virtual void amrex::Arena::free ( void *  pt )

pure virtual

Free a previously allocated block pointed to by pt.

Implemented in amrex::PArena, amrex::BArena, amrex::SArena, and amrex::CArena.

freeUnused()

virtual std::size_t amrex::Arena::freeUnused ( )

inlinevirtual

Release unused cached memory back to the system.

Returns

Number of bytes freed.

Reimplemented in amrex::CArena.

freeUnused_protected()

virtual std::size_t amrex::Arena::freeUnused_protected ( )

inlineprotectedvirtual

Reimplemented in amrex::CArena.

hasFreeDeviceMemory()

bool amrex::Arena::hasFreeDeviceMemory ( std::size_t  sz )

virtual

Does the device have enough free memory for allocating this much memory? For CPU builds, this always return true. This is not a const function because it may attempt to release memory back to the system.

Parameters

sz	Requested allocation size in bytes.

Reimplemented in amrex::CArena.

Initialize()

void amrex::Arena::Initialize ( bool  minimal )

static

Initialize the Arena subsystem (used internally by AMReX).

Parameters

minimal

When true, perform only the minimal setup required.

isDevice()

bool amrex::Arena::isDevice ( ) const

virtual

Check whether it is non-managed GPU device memory.

Note that isManaged, isDevice and isPinned are mutually exclusive. For memory allocated by cudaMalloc* etc. in GPU builds, one of them returns true. For CPU builds, they are always false.

Reimplemented in amrex::BArena, amrex::PArena, and amrex::SArena.

isDeviceAccessible()

bool amrex::Arena::isDeviceAccessible ( ) const

virtual

Check whether the memory is accessible on the device. Note that isDeviceAccessible and isHostAccessible can both be true.

Reimplemented in amrex::BArena, amrex::PArena, and amrex::SArena.

isHostAccessible()

bool amrex::Arena::isHostAccessible ( ) const

virtual

Check whether the memory is accessible on the host. Note that isDeviceAccessible and isHostAccessible can both be true.

Reimplemented in amrex::BArena, amrex::PArena, and amrex::SArena.

IsInitialized()

bool amrex::Arena::IsInitialized ( )

static

Whether the Arena subsystem is initialized.

isManaged()

bool amrex::Arena::isManaged ( ) const

virtual

Check whether it is managed GPU memory.

Note that isManaged, isDevice and isPinned are mutually exclusive. For memory allocated by cudaMalloc* etc. in GPU builds, one of them returns true. For CPU builds, they are always false.

Reimplemented in amrex::BArena, amrex::PArena, and amrex::SArena.

isPinned()

bool amrex::Arena::isPinned ( ) const

virtual

Check whether it is pinned host memory.

Note that isManaged, isDevice and isPinned are mutually exclusive. For memory allocated by cudaMalloc* etc. in GPU builds, one of them returns true. For CPU builds, they are always false.

Reimplemented in amrex::BArena, amrex::PArena, and amrex::SArena.

isStreamOrderedArena()

virtual bool amrex::Arena::isStreamOrderedArena ( ) const

inlinevirtual

Is this GPU stream ordered memory allocator?

Reimplemented in amrex::PArena, and amrex::SArena.

largestFreeBlock()

virtual std::size_t amrex::Arena::largestFreeBlock ( ) const

inlinevirtual

Return the largest free memory block already held by this Arena.

A return value of 0 means this query is not applicable or unknown.

Reimplemented in amrex::CArena.

operator=() [1/2]

Arena & amrex::Arena::operator= ( Arena &&  rhs )

delete

operator=() [2/2]

Arena & amrex::Arena::operator= ( const Arena &  rhs )

delete

out_of_memory_abort()

void amrex::Arena::out_of_memory_abort ( std::string const &  memory_type, std::size_t  nbytes, std::string const &  error_msg  )

staticprotected

PrintUsage()

void amrex::Arena::PrintUsage ( bool  print_max_usage = false )

static

Print memory usage information of all arenas.

This function reports memory usage statistics for all CArena-based AMReX arenas. It contains MPI collective calls and therefore must be called by all processes. The output is printed on the I/O process only.

Depending on the value of print_max_usage, the function prints either the current memory usage (when false) or the maximum memory usage recorded (when true).

Parameters

print_max_usage

whether to print the maximum usage or the current usage

PrintUsageToFiles()

void amrex::Arena::PrintUsageToFiles ( std::string const &  filename, std::string const &  message  )

static

Print memory usage information of all arenas to given file.

This function reports memory usage statistics for all CArena-based AMReX arenas. The output is appended to a file named {filename}.{rank}, where rank is the MPI rank of the process. Unlike PrintUsage, this does not contain MPI calls and therefore may be called independently on individual processes.

Parameters

filename	base name of the output file
message	message printed at the beginning

PrintUsageToStream()

void amrex::Arena::PrintUsageToStream ( std::ostream &  os, std::string const &  space  )

static

Print memory usage information of all arenas to a given output stream.

This function reports memory usage statistics for all CArena-based AMReX arenas. Unlike PrintUsage, this does not contain MPI calls and therefore may be called independently on individual processes.

Parameters

os	output stream
space	indentation prepended to printed lines

registerForProfiling()

void amrex::Arena::registerForProfiling

(

const std::string &

memory_name

)

Add this Arena to the list of Arenas that are profiled by TinyProfiler.

Parameters

memory_name

The name of this arena in the TinyProfiler output.

ResetMaxUsageCounter()

virtual void amrex::Arena::ResetMaxUsageCounter ( )

inlinevirtual

Reset the maximum usage counter. This is no-op in this implementation of the virtual function.

Reimplemented in amrex::CArena.

shrink_in_place()

virtual void * amrex::Arena::shrink_in_place ( void *  pt, std::size_t  sz  )

inlinevirtual

Shrink allocation size in-place.

In this implementation of the virtual function, a new allocation is always performed, and it returns the new pointer. Note that this function does NOT free the existing allocation, so it's the caller's responsibility to free the original pointer when appropriate.

Parameters

pt	Existing allocation to be shrunk.
sz	Target size for the new allocation.

Returns

Pointer to the resized allocation.

Reimplemented in amrex::CArena.

streamOrderedFree()

void amrex::Arena::streamOrderedFree ( void *  pt, gpuStream_t  stream  )

virtual

Reimplemented in amrex::PArena, and amrex::SArena.

Member Data Documentation

align_size

const std::size_t amrex::Arena::align_size = 256

static

The alignment of allocated memory 256 bytes is the default alignment that cudaMalloc uses. If the native allocation function were to give memory that has a smaller alignment than align_size, memory from the Arena will also only have this smaller alignment. In practice, native allocation functions have >= 256 bytes of alignment. In all cases, memory should be at least aligned to std::max_align_t, usually 16.

arena_info

ArenaInfo amrex::Arena::arena_info

protected

---

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

• /home/runner/work/amrex/amrex/Src/Base/AMReX_Arena.H
• /home/runner/work/amrex/amrex/Src/Base/AMReX_Arena.cpp