amrex::CArena Class Reference

A Concrete Class for Dynamic Memory Management using first fit. This is a coalescing memory manager. It allocates (possibly) large chunks of heap space and apportions it out as requested. It merges together neighboring chunks on each free(). 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. hunk_size is the minimum size of hunks of memory to allocate from the heap. If hunk_size == 0 we use DefaultHunkSize as specified below.
	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 freed.
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 amount of memory in this pointer. Return 0 for unknown pointer.
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?
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 = 16
	The alignment of allocated memory.

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
struct amrex::Arena::ArenaProfiler	m_profiler

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

Additional Inherited Members
Static Public Member Functions inherited from amrex::Arena
static std::size_t	align (std::size_t sz)
	Given a minimum required arena size of sz bytes, this returns the next largest arena size that will align to align_size bytes.
static void	Initialize (bool minimal)
	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 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

A Concrete Class for Dynamic Memory Management using first fit. This is a coalescing memory manager. It allocates (possibly) large chunks of heap space and apportions it out as requested. It merges together neighboring chunks on each free().

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. hunk_size is the minimum size of hunks of memory to allocate from the heap. If hunk_size == 0 we use DefaultHunkSize as specified below.

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.

Implements amrex::Arena.

freeableMemory()

std::size_t amrex::CArena::freeableMemory

(

)

const

Return the amount of memory that can be freed.

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.

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.

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 amount of memory in this pointer. Return 0 for unknown pointer.

Friends And Related Symbol Documentation

operator<<

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

friend

Member Data Documentation

carena_mutex

std::mutex amrex::CArena::carena_mutex

protected

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