Abstract placement policy: allocates and frees raw, correctly-aligned byte blocks. More...

#include <EBGeometry_MemoryResource.hpp>

Inheritance diagram for EBGeometry::MemoryResource:

[legend]

Public Member Functions
	MemoryResource ()=default
	Default constructor.

virtual	~MemoryResource ()=default
	Destructor.

	MemoryResource (const MemoryResource &)=delete
	Copy constructor. Deleted: a resource's identity is meaningful and non-copyable.

MemoryResource &	operator= (const MemoryResource &)=delete
	Copy assignment. Deleted: a resource's identity is meaningful and non-copyable.

virtual void *	allocate (size_t a_bytes, size_t a_alignment)=0
	Obtain a block of at least `a_bytes` bytes, aligned to `a_alignment`.

virtual void	deallocate (void *a_ptr, size_t a_bytes, size_t a_alignment) noexcept=0
	Release a block previously returned by allocate.

virtual bool	isHostAccessible () const noexcept=0
	Whether a plain host pointer dereference / `std::memcpy` is valid on returned blocks.

virtual bool	isDeviceAccessible () const noexcept=0
	Whether a device kernel may dereference returned blocks.

virtual void	copy (void a_dst, const MemoryResource &a_dstResource, const void a_src, const MemoryResource &a_srcResource, size_t a_bytes) const noexcept
	Copy a block between memory from two resources, one of which is this one.

Detailed Description

Abstract placement policy: allocates and frees raw, correctly-aligned byte blocks.

Runtime-virtual so that placement (host/device/managed/pinned) is a runtime choice. Allocation and deallocation are host-only operations – memory is never obtained from device code. The (bytes, alignment) pair is passed back to deallocate (the std::pmr convention), so a resource built on std::aligned_alloc / free needs no size bookkeeping.

The type is deliberately non-copyable: a resource's identity matters (two pools over the same resource share a placement), and copying an allocator has no meaning.

Note: This is one of the two deliberately non-trivial types of the memory foundation (it owns a vtable); everything stored inside a Pool is trivially copyable POD, but the resource and the pool themselves are not, so no std::is_trivially_copyable_v static_assert applies here.

Member Function Documentation

◆ allocate()

virtual void * EBGeometry::MemoryResource::allocate	(	size_t	a_bytes,
		size_t	a_alignment
	)

pure virtual

Obtain a block of at least a_bytes bytes, aligned to a_alignment.

Never returns null (a zero-byte request gets a block too); on failure the implementation aborts (EBGEOMETRY_REQUIRE for host memory, EBGEOMETRY_GPU_CHECK for memory from the GPU runtime), matching the library's no-exceptions convention.

Parameters

[in]	a_bytes	Number of bytes to allocate (may be zero).
[in]	a_alignment	Required alignment in bytes. Must be a power of two.

Returns: Pointer to the allocated block.

Implemented in EBGeometry::HostMemoryResource, EBGeometry::EmulatedDeviceMemoryResource, EBGeometry::DeviceMemoryResource, EBGeometry::ManagedMemoryResource, EBGeometry::PinnedMemoryResource, and EBGeometry::MappedMemoryResource.

◆ copy()

virtual void EBGeometry::MemoryResource::copy	(	void *	a_dst,
		const MemoryResource &	a_dstResource,
		const void *	a_src,
		const MemoryResource &	a_srcResource,
		size_t	a_bytes
	)		const

virtualnoexcept

Copy a block between memory from two resources, one of which is this one.

Pool::mirror calls this on whichever of its two resources is not host-accessible (or on the destination's, if both are). This implementation copies between host-accessible blocks and aborts for any other pair. The device resources override it with the GPU runtime's copy. That keeps every backend-specific call inside classes that exist only in translation units compiled with a GPU backend, so Pool::mirror compiles to the same code in every translation unit.

Parameters

[out]	a_dst	Destination block.
[in]	a_dstResource	Resource that allocated a_dst.
[in]	a_src	Source block.
[in]	a_srcResource	Resource that allocated a_src.
[in]	a_bytes	Number of bytes to copy.

Reimplemented in EBGeometry::DeviceMemoryResource, EBGeometry::ManagedMemoryResource, EBGeometry::PinnedMemoryResource, and EBGeometry::MappedMemoryResource.

◆ deallocate()

virtual void EBGeometry::MemoryResource::deallocate	(	void *	a_ptr,
		size_t	a_bytes,
		size_t	a_alignment
	)

pure virtualnoexcept

Release a block previously returned by allocate.

Parameters

[in]	a_ptr	Pointer previously returned by allocate (null is a no-op).
[in]	a_bytes	The same byte count passed to the matching allocate call.
[in]	a_alignment	The same alignment passed to the matching allocate call.