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
void *	allocate (cuda::stream_ref stream, std::size_t size, std::size_t alignment=rmm::CUDA_ALLOCATION_ALIGNMENT)
	Allocates pinned host memory associated with a CUDA stream. More...

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

bool	operator== (PinnedMemoryResource const &other) const noexcept
	Equality comparison. 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...

Static Public Member Functions
static std::optional< 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::optional< PinnedMemoryResource >	from_options (config::Options options)
	Construct from configuration options. More...

Static Public Attributes
static constexpr std::nullopt_t	Disabled = std::nullopt
	Sentinel value indicating that pinned host memory is disabled.

static constexpr bool	EnabledByDefault = false
	Whether pinned host memory is enabled by default.

static constexpr std::string_view	DefaultInitiPoolSizeFactor = "0%"
	Fraction of total host memory per GPU used as the initial pinned pool size when no explicit `pinned_initial_pool_size` option is provided. More...

static constexpr std::string_view	DefaultMaxPoolSizeFactor = "80%"
	Fraction of total host memory per GPU used as the maximum pinned pool size when no explicit `pinned_max_pool_size` option is provided. More...

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

Detailed Description

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

Inherits from cuda::mr::shared_resource<RmmResourceAdaptorImpl<cuda::pinned_memory_pool>>, which holds the pool directly inside the shared control block — no extra heap allocation for the pool itself. Copies share the same underlying pool and memory statistics.

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 93 of file pinned_memory_resource.hpp.

Member Function Documentation

◆ allocate()

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

inline

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.

Definition at line 170 of file pinned_memory_resource.hpp.

◆ 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 210 of file pinned_memory_resource.hpp.

◆ deallocate()

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

inlinenoexcept

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.

Definition at line 186 of file pinned_memory_resource.hpp.

◆ from_options()

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

static

Construct from configuration options.

Recognized options:

pinned_memory (bool): enables pinned memory; defaults to EnabledByDefault.
pinned_initial_pool_size (nbytes string): initial pool size; defaults to get_host_memory_per_gpu() * DefaultInitiPoolSizeFactor.
pinned_max_pool_size (nbytes string or empty): maximum pool size; defaults to get_host_memory_per_gpu() * DefaultMaxPoolSizeFactor.

Parameters

options Configuration options.

Returns: A PinnedMemoryResource if pinned memory is enabled and supported, otherwise std::nullopt.

◆ 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 219 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).

◆ make_if_available()

static std::optional<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 PinnedMemoryResource when supported, otherwise std::nullopt.

See also: PinnedMemoryResource::PinnedMemoryResource

◆ operator==()

bool rapidsmpf::PinnedMemoryResource::operator== ( PinnedMemoryResource const & other ) const

inlinenoexcept

Equality comparison.

Parameters

other The other resource to compare.

Returns: True if the two resources share the same underlying shared state.

Definition at line 201 of file pinned_memory_resource.hpp.

◆ 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 228 of file pinned_memory_resource.hpp.

Member Data Documentation

◆ DefaultInitiPoolSizeFactor

constexpr std::string_view rapidsmpf::PinnedMemoryResource::DefaultInitiPoolSizeFactor = "0%"

staticconstexpr

Fraction of total host memory per GPU used as the initial pinned pool size when no explicit pinned_initial_pool_size option is provided.

Applied as: initial_pool_size = get_host_memory_per_gpu() * DefaultInitiPoolSizeFactor.

Definition at line 113 of file pinned_memory_resource.hpp.

◆ DefaultMaxPoolSizeFactor

constexpr std::string_view rapidsmpf::PinnedMemoryResource::DefaultMaxPoolSizeFactor = "80%"

staticconstexpr

Fraction of total host memory per GPU used as the maximum pinned pool size when no explicit pinned_max_pool_size option is provided.

Applied as: max_pool_size = get_host_memory_per_gpu() * DefaultMaxPoolSizeFactor. get_host_memory_per_gpu() is computed as total host memory divided by the number of GPUs visible to the system.

Definition at line 123 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

Member Function Documentation

◆ allocate()

◆ current_allocated()

◆ deallocate()

◆ from_options()

◆ get_main_memory_record()

◆ get_memory_available_cb()

◆ make_if_available()

◆ operator==()

◆ properties()

Member Data Documentation

◆ DefaultInitiPoolSizeFactor

◆ DefaultMaxPoolSizeFactor