amrex::CArena Class Reference

Coalescing first-fit dynamic memory arena. More...

#include <AMReX_CArena.H>

Inheritance diagram for amrex::CArena:

Classes
class	Node
	The nodes in our free list and block list. More...

Public Member Functions
	CArena (std::size_t hunk_size=0, ArenaInfo info=ArenaInfo())
	Construct a coalescing memory manager.
	CArena (const CArena &rhs)=delete
	CArena (CArena &&rhs)=delete
CArena &	operator= (const CArena &rhs)=delete
CArena &	operator= (CArena &&rhs)=delete
	~CArena () override
	The destructor.
void *	alloc (std::size_t nbytes) final
	Allocate some memory.
std::pair< void *, std::size_t >	alloc_in_place (void *pt, std::size_t szmin, std::size_t szmax) final
	Allocate memory in-place if possible.
void *	shrink_in_place (void *pt, std::size_t new_size) final
	Shrink allocation size in-place.
void	free (void *vp) final
	Free up allocated memory. Merge neighboring free memory chunks into largest possible chunk.
std::size_t	freeUnused () final
	Free unused memory back to the system. Return value is the amount of memory freed.
std::size_t	freeableMemory () const
	Return the amount of memory that can be released back to the heap.
std::size_t	largestFreeBlock () const final
	Return the largest free memory block already held by this CArena.
bool	hasFreeDeviceMemory (std::size_t sz) final
	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.
std::size_t	heap_space_used () const noexcept
	The current amount of heap space used by the CArena object.
std::size_t	heap_space_actually_used () const noexcept
	Return the total amount of memory given out via alloc.
std::size_t	sizeOf (void *p) const noexcept
	Return the size of the allocation referenced by p (0 if unknown).
void	PrintUsage (std::string const &name, bool print_max_usage) const
	Print memory usage information of this arena.
void	PrintUsage (std::ostream &os, std::string const &name, std::string const &space) const
	Print memory usage information of this arena to a given output stream.
void	ResetMaxUsageCounter () final
	Reset the maximum usage counter.
Public Member Functions inherited from amrex::Arena
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 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.
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.

Static Public Attributes
static constexpr std::size_t	DefaultHunkSize = 1024*1024*8
	The default memory hunk size to grab from the heap.
Static Public Attributes inherited from amrex::Arena
static const std::size_t	align_size = 256

Protected Types
using	NL = std::set< Node >
	The type of our freelist and blocklist. We use a set sorted from lo to hi memory addresses.

Protected Member Functions
void *	alloc_protected (std::size_t nbytes)
std::size_t	freeUnused_protected () final
Protected Member Functions inherited from amrex::Arena
void *	allocate_system (std::size_t nbytes)
void	deallocate_system (void *p, std::size_t nbytes)

Protected Attributes
std::vector< std::pair< void *, std::size_t > >	m_alloc
	The list of blocks allocated.
NL	m_freelist
	The free list of allocated but not currently used blocks. Maintained in lo to hi memory sorted order.
std::unordered_set< Node, Node::hash >	m_busylist
	The list of busy blocks. A block is either on the freelist or on the blocklist, but not on both.
std::size_t	m_hunk
	The minimal size of hunks to request from system.
std::size_t	m_used {0}
	The amount of heap space currently allocated.
std::size_t	m_max_used {0}
	The max amount of heap space currently allocated.
std::size_t	m_actually_used {0}
	The amount of memory given out via alloc().
std::size_t	m_max_actually_used {0}
	The max amount of memory given out via alloc().
std::mutex	carena_mutex
Protected Attributes inherited from amrex::Arena
ArenaInfo	arena_info

Friends
std::ostream &	operator<< (std::ostream &os, const CArena &arena)
	Print a summary of the arena's free and busy lists to os.

Additional Inherited Members
Static Public Member Functions inherited from amrex::Arena
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 Protected Member Functions inherited from amrex::Arena
static void	out_of_memory_abort (std::string const &memory_type, std::size_t nbytes, std::string const &error_msg)

Detailed Description

Coalescing first-fit dynamic memory arena.

Allocates large hunks from the heap and sub-allocates from them on demand. Neighboring free blocks are merged on each free() call to reduce fragmentation.

Member Typedef Documentation

NL

using amrex::CArena::NL = std::set<Node>

protected

The type of our freelist and blocklist. We use a set sorted from lo to hi memory addresses.

Constructor & Destructor Documentation

CArena() [1/3]

amrex::CArena::CArena	(	std::size_t	hunk_size = 0,
		ArenaInfo	info = ArenaInfo()
	)

Construct a coalescing memory manager.

Parameters

hunk_size	Minimum size of heap hunks to allocate. Defaults to DefaultHunkSize when 0.
info	Arena configuration flags.

CArena() [2/3]

amrex::CArena::CArena ( const CArena &  rhs )

delete

CArena() [3/3]

amrex::CArena::CArena ( CArena &&  rhs )

delete

~CArena()

amrex::CArena::~CArena ( )

override

The destructor.

Member Function Documentation

alloc()

void * amrex::CArena::alloc ( std::size_t  nbytes )

finalvirtual

Allocate some memory.

Implements amrex::Arena.

alloc_in_place()

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

finalvirtual

Allocate memory in-place if possible.

This function tries to allocate in-place by extending the capacity of an existing pointer. If it's possible to extend the given pointer to the minimum required size without performing a new allocation, this function will return the original pointer back along with the new size (which may be in the range of [szmin,szmax]); otherwise a new allocation is performed to allocate the maximum requested size.

Note that this function does NOT free the existing allocation, even when a new memory allocation is performed. So it's the caller's responsibility to free the original pointer when appropriate. A new allocation can be detected by comparing the returned pointer with the input pointer.

Parameters

pt	existing pointer
szmin	minimum required size in bytes
szmax	maximum requested size in bytes

Returns

pair of pointer and allocation size in bytes

Reimplemented from amrex::Arena.

alloc_protected()

void * amrex::CArena::alloc_protected ( std::size_t  nbytes )

protected

free()

void amrex::CArena::free ( void *  vp )

finalvirtual

Free up allocated memory. Merge neighboring free memory chunks into largest possible chunk.

Parameters

vp	Pointer previously returned by alloc() or alloc_in_place().

Implements amrex::Arena.

freeableMemory()

std::size_t amrex::CArena::freeableMemory

(

)

const

Return the amount of memory that can be released back to the heap.

freeUnused()

std::size_t amrex::CArena::freeUnused ( )

finalvirtual

Free unused memory back to the system. Return value is the amount of memory freed.

Reimplemented from amrex::Arena.

freeUnused_protected()

std::size_t amrex::CArena::freeUnused_protected ( )

finalprotectedvirtual

Reimplemented from amrex::Arena.

hasFreeDeviceMemory()

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

finalvirtual

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	Number of bytes requested.

Reimplemented from amrex::Arena.

heap_space_actually_used()

std::size_t amrex::CArena::heap_space_actually_used ( ) const

noexcept

Return the total amount of memory given out via alloc.

heap_space_used()

std::size_t amrex::CArena::heap_space_used ( ) const

noexcept

The current amount of heap space used by the CArena object.

largestFreeBlock()

std::size_t amrex::CArena::largestFreeBlock ( ) const

finalvirtual

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

Reimplemented from amrex::Arena.

operator=() [1/2]

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

delete

operator=() [2/2]

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

delete

PrintUsage() [1/2]

void amrex::CArena::PrintUsage	(	std::ostream &	os,
		std::string const &	name,
		std::string const &	space
	)		const

Print memory usage information of this arena to a given output stream.

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

Parameters

os	output stream
name	name of the arena used in printing.
space	indentation prepended to printed lines

PrintUsage() [2/2]

void amrex::CArena::PrintUsage	(	std::string const &	name,
		bool	print_max_usage
	)		const

Print memory usage information of this arena.

This function reports memory usage statistics for this CArena. 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 recoreded (when true).

Parameters

name	name of the arena used in printing.
print_max_usage	whether to print the maximum usage or the current usage.

ResetMaxUsageCounter()

void amrex::CArena::ResetMaxUsageCounter ( )

inlinefinalvirtual

Reset the maximum usage counter.

Reimplemented from amrex::Arena.

shrink_in_place()

void * amrex::CArena::shrink_in_place ( void *  pt, std::size_t  new_size  )

finalvirtual

Shrink allocation size in-place.

This function shrinks the existing allocation of the given pointer to a new size. It's a runtime error, if the requested new size is larger than the original size. In the special case of pt == nullptr or new_size == 0, this does not do anything other than returning nullptr.

Parameters

pt	existing pointer
new_size	new size after shrinking

Returns

either the original pointer or nullptr if the requested new size is zero.

Reimplemented from amrex::Arena.

sizeOf()

std::size_t amrex::CArena::sizeOf ( void *  p ) const

noexcept

Return the size of the allocation referenced by p (0 if unknown).

Parameters

p	Pointer previously returned by alloc().

Friends And Related Symbol Documentation

operator<<

std::ostream & operator<< ( std::ostream &  os, const CArena &  arena  )

friend

Print a summary of the arena's free and busy lists to os.

Member Data Documentation

carena_mutex

std::mutex amrex::CArena::carena_mutex

mutableprotected

DefaultHunkSize

constexpr std::size_t amrex::CArena::DefaultHunkSize = 1024*1024*8

staticconstexpr

The default memory hunk size to grab from the heap.

m_actually_used

std::size_t amrex::CArena::m_actually_used {0}

protected

The amount of memory given out via alloc().

m_alloc

std::vector<std::pair<void*,std::size_t> > amrex::CArena::m_alloc

protected

The list of blocks allocated.

m_busylist

std::unordered_set<Node, Node::hash> amrex::CArena::m_busylist

protected

The list of busy blocks. A block is either on the freelist or on the blocklist, but not on both.

m_freelist

NL amrex::CArena::m_freelist

protected

The free list of allocated but not currently used blocks. Maintained in lo to hi memory sorted order.

m_hunk

std::size_t amrex::CArena::m_hunk

protected

The minimal size of hunks to request from system.

m_max_actually_used

std::size_t amrex::CArena::m_max_actually_used {0}

protected

The max amount of memory given out via alloc().

m_max_used

std::size_t amrex::CArena::m_max_used {0}

protected

The max amount of heap space currently allocated.

m_used

std::size_t amrex::CArena::m_used {0}

protected

The amount of heap space currently allocated.

---

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

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