Memory resource that provides pinned (page-locked) host memory using a pool. More...

#include <pinned_memory_resource.hpp>

Inheritance diagram for rapidsmpf::PinnedMemoryResource:

Public Member Functions
	PinnedMemoryResource (int numa_id=get_current_numa_node(), PinnedPoolProperties pool_properties={})
	Construct a pinned (page-locked) host memory resource. More...

void *	allocate (rmm::cuda_stream_view stream, std::size_t size, std::size_t alignment=rmm::CUDA_ALLOCATION_ALIGNMENT) override
	Allocates pinned host memory associated with a CUDA stream. More...

void	deallocate (rmm::cuda_stream_view stream, void *ptr, std::size_t size, std::size_t alignment=rmm::CUDA_ALLOCATION_ALIGNMENT) noexcept override
	Deallocates pinned host memory associated with a CUDA stream. More...

bool	is_equal (HostMemoryResource const &other) const noexcept override
	Compares this resource to another resource. More...

std::int64_t	current_allocated () const noexcept
	Returns the total number of currently allocated bytes. More...

ScopedMemoryRecord	get_main_memory_record () const
	Returns the main memory record for the pinned pool. More...

constexpr PinnedPoolProperties const &	properties () const noexcept
	Returns the properties used to configure the pool. More...

std::function< std::int64_t()>	get_memory_available_cb () const
	Returns a memory-availability callback for the pinned pool, if the pool has a configured maximum size. More...

Public Member Functions inherited from rapidsmpf::HostMemoryResource
	HostMemoryResource ()=default
	Default constructor.

virtual	~HostMemoryResource ()=default
	Virtual destructor to allow polymorphic use.

	HostMemoryResource (HostMemoryResource const &)=default
	Copyable.

	HostMemoryResource (HostMemoryResource &&)=default
	Movable.

HostMemoryResource &	operator= (HostMemoryResource const &)=default
	Copy assignment. More...

HostMemoryResource &	operator= (HostMemoryResource &&)=default
	Move assignment. More...

void *	allocate_sync (std::size_t, std::size_t)
	Synchronously allocates host memory is disabled. More...

void	deallocate_sync (void *, std::size_t, std::size_t)
	Synchronously deallocates host memory is disabled. More...

virtual bool	is_equal ([[maybe_unused]] HostMemoryResource const &other) const noexcept
	Compares this resource to another resource. More...

bool	operator== (HostMemoryResource const &other) const noexcept
	Compares this resource to another resource. More...

bool	operator!= (HostMemoryResource const &other) const noexcept
	Compares this resource to another resource. More...

Static Public Member Functions
static std::shared_ptr< PinnedMemoryResource >	make_if_available (int numa_id=get_current_numa_node(), PinnedPoolProperties pool_properties={})
	Create a pinned memory resource if the system supports pinned memory. More...

static std::shared_ptr< PinnedMemoryResource >	from_options (config::Options options)
	Construct from configuration options. More...

Static Public Attributes
static constexpr auto	Disabled = nullptr
	Sentinel value used to disable pinned host memory.

Friends
void	get_property (PinnedMemoryResource const &, cuda::mr::device_accessible) noexcept
	Enables the `cuda::mr::host_accessible` property. More...

Detailed Description

Memory resource that provides pinned (page-locked) host memory using a pool.

This resource allocates and deallocates pinned host memory asynchronously through CUDA streams. It offers higher bandwidth and lower latency for device transfers compared to regular pageable host memory.

Definition at line 89 of file pinned_memory_resource.hpp.

Constructor & Destructor Documentation

◆ PinnedMemoryResource()

rapidsmpf::PinnedMemoryResource::PinnedMemoryResource	(	int	numa_id = `get_current_numa_node()`,
		PinnedPoolProperties	pool_properties = `{}`
	)

Construct a pinned (page-locked) host memory resource.

The pool has no maximum size. To restrict its growth, use BufferResource::LimitAvailableMemory or a similar mechanism.

Parameters

numa_id	NUMA node from which memory should be allocated. By default, the resource uses the NUMA node of the calling thread.
pool_properties	Properties for configuring the pinned memory pool.

Exceptions

rapidsmpf::cuda_error If pinned host memory pools are not supported by the current CUDA version or if CUDA initialization fails.

Member Function Documentation

◆ allocate()

void* rapidsmpf::PinnedMemoryResource::allocate	(	rmm::cuda_stream_view	stream,
		std::size_t	size,
		std::size_t	alignment = `rmm::CUDA_ALLOCATION_ALIGNMENT`
	)

overridevirtual

Allocates pinned host memory associated with a CUDA stream.

Parameters

stream	CUDA stream associated with the allocation.
size	Number of bytes to at least allocate.
alignment	Required alignment.

Returns: Pointer to the allocated memory.

Exceptions

std::bad_alloc	If the allocation fails.
std::invalid_argument	If `alignment` is not a valid alignment.

Reimplemented from rapidsmpf::HostMemoryResource.

◆ current_allocated()

std::int64_t rapidsmpf::PinnedMemoryResource::current_allocated ( ) const

inlinenoexcept

Returns the total number of currently allocated bytes.

Returns: The total number of currently allocated bytes.

Definition at line 186 of file pinned_memory_resource.hpp.

◆ deallocate()

void rapidsmpf::PinnedMemoryResource::deallocate	(	rmm::cuda_stream_view	stream,
		void *	ptr,
		std::size_t	size,
		std::size_t	alignment = `rmm::CUDA_ALLOCATION_ALIGNMENT`
	)

overridevirtualnoexcept

Deallocates pinned host memory associated with a CUDA stream.

Parameters

stream	CUDA stream associated with operations that used `ptr`.
ptr	Pointer to the memory to deallocate. May be nullptr.
size	Number of bytes previously allocated at `ptr`.
alignment	Alignment originally used for the allocation.

Reimplemented from rapidsmpf::HostMemoryResource.

◆ from_options()

static std::shared_ptr<PinnedMemoryResource> rapidsmpf::PinnedMemoryResource::from_options ( config::Options options )

static

Construct from configuration options.

Parameters

options Configuration options.

Returns: A shared pointer to the constructed PinnedMemoryResource instance.

◆ get_main_memory_record()

ScopedMemoryRecord rapidsmpf::PinnedMemoryResource::get_main_memory_record ( ) const

inline

Returns the main memory record for the pinned pool.

Returns: The main memory record for the pinned pool.

Definition at line 195 of file pinned_memory_resource.hpp.

◆ get_memory_available_cb()

std::function<std::int64_t()> rapidsmpf::PinnedMemoryResource::get_memory_available_cb ( ) const

Returns a memory-availability callback for the pinned pool, if the pool has a configured maximum size.

Returns: A callable std::int64_t(). If no maximum pool size is configured, returns std::numeric_limits<std::int64_t>::max (unbounded).

◆ is_equal()

bool rapidsmpf::PinnedMemoryResource::is_equal ( HostMemoryResource const & other ) const

overridenoexcept

Compares this resource to another resource.

Two resources are considered equal if memory allocated by one may be deallocated by the other.

Parameters

other The resource to compare with.

Returns: true because all instances of this base class are considered equal.

◆ make_if_available()

static std::shared_ptr<PinnedMemoryResource> rapidsmpf::PinnedMemoryResource::make_if_available	(	int	numa_id = `get_current_numa_node()`,
		PinnedPoolProperties	pool_properties = `{}`
	)

static

Create a pinned memory resource if the system supports pinned memory.

Parameters

numa_id	The NUMA node to associate with the resource. Defaults to the current NUMA node.
pool_properties	Properties for configuring the pinned memory pool.

Returns: A shared pointer to a new PinnedMemoryResource when supported, otherwise PinnedMemoryResource::Disabled.

See also: PinnedMemoryResource::PinnedMemoryResource

◆ properties()

constexpr PinnedPoolProperties const& rapidsmpf::PinnedMemoryResource::properties ( ) const

inlineconstexprnoexcept

Returns the properties used to configure the pool.

Returns: The properties used to configure the pool.

Definition at line 204 of file pinned_memory_resource.hpp.

Friends And Related Function Documentation

◆ get_property

void get_property	(	PinnedMemoryResource const &	,
		cuda::mr::device_accessible
	)

friend

Enables the cuda::mr::host_accessible property.

This property declares that a HostMemoryResource provides host accessible memory.

Definition at line 222 of file pinned_memory_resource.hpp.

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

/__w/rapidsmpf/rapidsmpf/cpp/include/rapidsmpf/memory/pinned_memory_resource.hpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ PinnedMemoryResource()

Member Function Documentation

◆ allocate()

◆ current_allocated()

◆ deallocate()

◆ from_options()

◆ get_main_memory_record()

◆ get_memory_available_cb()

◆ is_equal()

◆ make_if_available()

◆ properties()

Friends And Related Function Documentation

◆ get_property