A coalescing best-fit suballocator which uses a pool of memory allocated from an upstream memory_resource. More...

#include <pool_memory_resource.hpp>

Inheritance diagram for rmm::mr::pool_memory_resource< Upstream >:

[legend]

Collaboration diagram for rmm::mr::pool_memory_resource< Upstream >:

[legend]

Public Member Functions
	pool_memory_resource (Upstream *upstream_mr, thrust::optional< std::size_t > initial_pool_size=thrust::nullopt, thrust::optional< std::size_t > maximum_pool_size=thrust::nullopt)
	Construct a `pool_memory_resource` and allocate the initial device memory pool using `upstream_mr`. More...

template<typename Upstream2 = Upstream, cuda::std::enable_if_t< cuda::mr::async_resource< Upstream2 >, int > = 0>
	pool_memory_resource (Upstream2 &upstream_mr, thrust::optional< std::size_t > initial_pool_size=thrust::nullopt, thrust::optional< std::size_t > maximum_pool_size=thrust::nullopt)
	Construct a `pool_memory_resource` and allocate the initial device memory pool using `upstream_mr`. More...

	~pool_memory_resource () override
	Destroy the `pool_memory_resource` and deallocate all memory it allocated using the upstream resource.

	pool_memory_resource (pool_memory_resource const &)=delete

	pool_memory_resource (pool_memory_resource &&)=delete

pool_memory_resource &	operator= (pool_memory_resource const &)=delete

pool_memory_resource &	operator= (pool_memory_resource &&)=delete

bool	supports_streams () const noexcept override
	Queries whether the resource supports use of non-null CUDA streams for allocation/deallocation. More...

bool	supports_get_mem_info () const noexcept override
	Query whether the resource supports the get_mem_info API. More...

const Upstream &	upstream_resource () const noexcept
	Get the upstream memory_resource object. More...

Upstream *	get_upstream () const noexcept
	Get the upstream memory_resource object. More...

std::size_t	pool_size () const noexcept
	Computes the size of the current pool. More...

Protected Types
using	free_list = detail::coalescing_free_list
	The free list implementation.

using	block_type = free_list::block_type
	The type of block returned by the free list.

using	lock_guard = std::lock_guard< std::mutex >
	Type of lock used to synchronize access.

Protected Member Functions
std::size_t	get_maximum_allocation_size () const
	Get the maximum size of allocations supported by this memory resource. More...

block_type	try_to_expand (std::size_t try_size, std::size_t min_size, cuda_stream_view stream)
	Try to expand the pool by allocating a block of at least `min_size` bytes from upstream. More...

void	initialize_pool (thrust::optional< std::size_t > initial_size, thrust::optional< std::size_t > maximum_size)
	Allocate initial memory for the pool. More...

block_type	expand_pool (std::size_t size, free_list &blocks, cuda_stream_view stream)
	Allocate space from upstream to supply the suballocation pool and return a sufficiently sized block. More...

std::size_t	size_to_grow (std::size_t size) const
	Given a minimum size, computes an appropriate size to grow the pool. More...

thrust::optional< block_type >	block_from_upstream (std::size_t size, cuda_stream_view stream)
	Allocate a block from upstream to expand the suballocation pool. More...

split_block	allocate_from_block (block_type const &block, std::size_t size)
	Splits `block` if necessary to return a pointer to memory of `size` bytes. More...

block_type	free_block (void *ptr, std::size_t size) noexcept
	Finds, frees and returns the block associated with pointer `ptr`. More...

void	release ()
	Free all memory allocated from the upstream memory_resource.

std::pair< std::size_t, std::size_t >	free_list_summary (free_list const &blocks)
	Get the largest available block size and total free size in the specified free list. More...

std::pair< std::size_t, std::size_t >	do_get_mem_info (cuda_stream_view stream) const override
	Get free and available memory for memory resource. More...

Friends
class	detail::stream_ordered_memory_resource< pool_memory_resource< Upstream >, detail::coalescing_free_list >

Detailed Description

template<typename Upstream>
class rmm::mr::pool_memory_resource< Upstream >

A coalescing best-fit suballocator which uses a pool of memory allocated from an upstream memory_resource.

Allocation (do_allocate()) and deallocation (do_deallocate()) are thread-safe. Also, this class is compatible with CUDA per-thread default stream.

Template Parameters

UpstreamResource memory_resource to use for allocating the pool. Implements rmm::mr::device_memory_resource interface.

Constructor & Destructor Documentation

◆ pool_memory_resource() [1/2]

template<typename Upstream >

rmm::mr::pool_memory_resource< Upstream >::pool_memory_resource	(	Upstream *	upstream_mr,
		thrust::optional< std::size_t >	initial_pool_size = `thrust::nullopt`,
		thrust::optional< std::size_t >	maximum_pool_size = `thrust::nullopt`
	)

inlineexplicit

Construct a pool_memory_resource and allocate the initial device memory pool using upstream_mr.

Exceptions

rmm::logic_error	if `upstream_mr == nullptr`
rmm::logic_error	if `initial_pool_size` is neither the default nor aligned to a multiple of pool_memory_resource::allocation_alignment bytes.
rmm::logic_error	if `maximum_pool_size` is neither the default nor aligned to a multiple of pool_memory_resource::allocation_alignment bytes.

Parameters

upstream_mr	The memory_resource from which to allocate blocks for the pool.
initial_pool_size	Minimum size, in bytes, of the initial pool. Defaults to half of the available memory on the current device.
maximum_pool_size	Maximum size, in bytes, that the pool can grow to. Defaults to all of the available memory on the current device.

◆ pool_memory_resource() [2/2]

template<typename Upstream >

template<typename Upstream2 = Upstream, cuda::std::enable_if_t< cuda::mr::async_resource< Upstream2 >, int > = 0>

rmm::mr::pool_memory_resource< Upstream >::pool_memory_resource	(	Upstream2 &	upstream_mr,
		thrust::optional< std::size_t >	initial_pool_size = `thrust::nullopt`,
		thrust::optional< std::size_t >	maximum_pool_size = `thrust::nullopt`
	)

inlineexplicit

Construct a pool_memory_resource and allocate the initial device memory pool using upstream_mr.

Exceptions

rmm::logic_error	if `upstream_mr == nullptr`
rmm::logic_error	if `initial_pool_size` is neither the default nor aligned to a multiple of pool_memory_resource::allocation_alignment bytes.
rmm::logic_error	if `maximum_pool_size` is neither the default nor aligned to a multiple of pool_memory_resource::allocation_alignment bytes.

Parameters

upstream_mr	The memory_resource from which to allocate blocks for the pool.
initial_pool_size	Minimum size, in bytes, of the initial pool. Defaults to half of the available memory on the current device.
maximum_pool_size	Maximum size, in bytes, that the pool can grow to. Defaults to all of the available memory on the current device.

Member Function Documentation

◆ allocate_from_block()

template<typename Upstream >

split_block rmm::mr::pool_memory_resource< Upstream >::allocate_from_block	(	block_type const &	block,
		std::size_t	size
	)

inlineprotected

Splits block if necessary to return a pointer to memory of size bytes.

If the block is split, the remainder is returned to the pool.

Parameters

block	The block to allocate from.
size	The size in bytes of the requested allocation.

Returns: A pair comprising the allocated pointer and any unallocated remainder of the input block.

◆ block_from_upstream()

template<typename Upstream >

thrust::optional<block_type> rmm::mr::pool_memory_resource< Upstream >::block_from_upstream	(	std::size_t	size,
		cuda_stream_view	stream
	)

inlineprotected

Allocate a block from upstream to expand the suballocation pool.

Parameters

size	The size in bytes to allocate from the upstream resource
stream	The stream on which the memory is to be used.

Returns: block_type The allocated block

◆ do_get_mem_info()

template<typename Upstream >

std::pair<std::size_t, std::size_t> rmm::mr::pool_memory_resource< Upstream >::do_get_mem_info ( cuda_stream_view stream ) const

inlineoverrideprotected

Get free and available memory for memory resource.

Exceptions

nothing

Parameters

stream to execute on

Returns: std::pair contaiing free_size and total_size of memory

◆ expand_pool()

template<typename Upstream >

block_type rmm::mr::pool_memory_resource< Upstream >::expand_pool	(	std::size_t	size,
		free_list &	blocks,
		cuda_stream_view	stream
	)

inlineprotected

Allocate space from upstream to supply the suballocation pool and return a sufficiently sized block.

Parameters

size	The minimum size to allocate
blocks	The free list (ignored in this implementation)
stream	The stream on which the memory is to be used.

Returns: block_type a block of at least size bytes

◆ free_block()

template<typename Upstream >

block_type rmm::mr::pool_memory_resource< Upstream >::free_block	(	void *	ptr,
		std::size_t	size
	)

inlineprotectednoexcept

Finds, frees and returns the block associated with pointer ptr.

Parameters

ptr	The pointer to the memory to free.
size	The size of the memory to free. Must be equal to the original allocation size.

Returns: The (now freed) block associated with p. The caller is expected to return the block to the pool.

◆ free_list_summary()

template<typename Upstream >

std::pair<std::size_t, std::size_t> rmm::mr::pool_memory_resource< Upstream >::free_list_summary ( free_list const & blocks )

inlineprotected

Get the largest available block size and total free size in the specified free list.

This is intended only for debugging

Parameters

blocks The free list from which to return the summary

Returns: std::pair<std::size_t, std::size_t> Pair of largest available block, total free size

◆ get_maximum_allocation_size()

template<typename Upstream >

std::size_t rmm::mr::pool_memory_resource< Upstream >::get_maximum_allocation_size ( ) const

inlineprotected

Get the maximum size of allocations supported by this memory resource.

Note this does not depend on the memory size of the device. It simply returns the maximum value of std::size_t

Returns: std::size_t The maximum size of a single allocation supported by this memory resource

◆ get_upstream()

template<typename Upstream >

Upstream* rmm::mr::pool_memory_resource< Upstream >::get_upstream ( ) const

inlinenoexcept

Get the upstream memory_resource object.

Returns: UpstreamResource* the upstream memory resource.

◆ initialize_pool()

template<typename Upstream >

void rmm::mr::pool_memory_resource< Upstream >::initialize_pool	(	thrust::optional< std::size_t >	initial_size,
		thrust::optional< std::size_t >	maximum_size
	)

inlineprotected

Allocate initial memory for the pool.

If initial_size is unset, then queries the upstream memory resource for available memory if upstream supports get_mem_info, or queries the device (using CUDA API) for available memory if not. Then attempts to initialize to half the available memory.

If initial_size is set, then tries to initialize the pool to that size.

Parameters

initial_size	The optional initial size for the pool
maximum_size	The optional maximum size for the pool

◆ pool_size()

template<typename Upstream >

std::size_t rmm::mr::pool_memory_resource< Upstream >::pool_size ( ) const

inlinenoexcept

Computes the size of the current pool.

Includes allocated as well as free memory.

Returns: std::size_t The total size of the currently allocated pool.

◆ size_to_grow()

template<typename Upstream >

std::size_t rmm::mr::pool_memory_resource< Upstream >::size_to_grow ( std::size_t size ) const

inlineprotected

Given a minimum size, computes an appropriate size to grow the pool.

Strategy is to try to grow the pool by half the difference between the configured maximum pool size and the current pool size, if the maximum pool size is set. If it is not set, try to double the current pool size.

Returns 0 if the requested size cannot be satisfied.

Parameters

size	The size of the minimum allocation immediately needed

Returns: std::size_t The computed size to grow the pool.

◆ supports_get_mem_info()

template<typename Upstream >

bool rmm::mr::pool_memory_resource< Upstream >::supports_get_mem_info ( ) const

inlineoverridenoexcept

Query whether the resource supports the get_mem_info API.

Returns: bool false

◆ supports_streams()

template<typename Upstream >

bool rmm::mr::pool_memory_resource< Upstream >::supports_streams ( ) const

inlineoverridenoexcept

Queries whether the resource supports use of non-null CUDA streams for allocation/deallocation.

Returns: bool true.

◆ try_to_expand()

template<typename Upstream >

block_type rmm::mr::pool_memory_resource< Upstream >::try_to_expand	(	std::size_t	try_size,
		std::size_t	min_size,
		cuda_stream_view	stream
	)

inlineprotected

Try to expand the pool by allocating a block of at least min_size bytes from upstream.

Attempts to allocate try_size bytes from upstream. If it fails, it iteratively reduces the attempted size by half until min_size, returning the allocated block once it succeeds.

Exceptions

rmm::bad_alloc if min_size bytes cannot be allocated from upstream or maximum pool size is exceeded.

Parameters

try_size	The initial requested size to try allocating.
min_size	The minimum requested size to try allocating.
stream	The stream on which the memory is to be used.

Returns: block_type a block of at least min_size bytes

◆ upstream_resource()

template<typename Upstream >

const Upstream& rmm::mr::pool_memory_resource< Upstream >::upstream_resource ( ) const

inlinenoexcept

Get the upstream memory_resource object.

Returns: const reference to the upstream memory resource.

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

pool_memory_resource.hpp

Public Member Functions

Protected Types

Protected Member Functions

Friends

Detailed Description

template<typename Upstream> class rmm::mr::pool_memory_resource< Upstream >

Constructor & Destructor Documentation

◆ pool_memory_resource() [1/2]

◆ pool_memory_resource() [2/2]

Member Function Documentation

◆ allocate_from_block()

◆ block_from_upstream()

◆ do_get_mem_info()

◆ expand_pool()

◆ free_block()

◆ free_list_summary()

◆ get_maximum_allocation_size()

◆ get_upstream()

◆ initialize_pool()

◆ pool_size()

◆ size_to_grow()

◆ supports_get_mem_info()

◆ supports_streams()

◆ try_to_expand()

◆ upstream_resource()

template<typename Upstream>
class rmm::mr::pool_memory_resource< Upstream >