gmx::HostAllocationPolicy Class Reference

#include <gromacs/gpu_utils/hostallocator.h>

Description

Policy class for configuring gmx::Allocator, to manage allocations of memory that may be needed for e.g. GPU transfers.

This allocator has state, so is most useful in cases where it is not known at compile time whether the allocated memory will be transferred to some device. It will increase the size of containers that use it. If the GROMACS build is configured with CUDA support, then memory will be allocated with PageAlignedAllocator, and that page pinned to physical memory if the pinning mode has been activated. If pinning mode is deactivated, or the GROMACS build does not support CUDA, then the memory will be allocated with AlignedAllocator. The pin() and unpin() methods work with the CUDA build, and silently do nothing otherwise. In future, we may modify or generalize this to work differently in other cases.

The intended use is to configure gmx::Allocator with this class as its policy class, and then to use e.g. std::vector::get_allocator().getPolicy() to control whether the allocation policy should activate its pinning mode. The policy object can also be used to explicitly pin() and unpin() the buffer when it is using PinningPolicy::PinnedIfSupported. The policy object is returned by value (as required by the C++ standard for get_allocator(), which copies a std::shared_ptr, so the policy object should be retrieved sparingly, e.g. only upon resize of the allocation. (Normal operation of the vector, e.g. during resize, incurs only the cost of the pointer indirection needed to consult the current state of the allocation policy.)

Todo:

As a minor optimization, consider also having a stateless version of this policy, which might be slightly faster or more convenient to use in the cases where it is known at compile time that the allocation will be used to transfer to a GPU.

Public Types
using	propagate_on_container_copy_assignment = std::false_type
	Don't propagate for copy.
using	propagate_on_container_move_assignment = std::true_type
	Propagate for move.
using	propagate_on_container_swap = std::true_type
	Propagate for move.

Public Member Functions
	HostAllocationPolicy (PinningPolicy policy=PinningPolicy::CannotBePinned)
	Constructor.
std::size_t	alignment () const noexcept
	Return the alignment size currently used by the active pinning policy.
void *	malloc (std::size_t bytes) const noexcept
	Allocate and perhaps pin page-aligned memory suitable for e.g. GPU transfers. More...
void	free (void *buffer) const noexcept
	Free the memory, after unpinning (if appropriate). More...
PinningPolicy	pinningPolicy () const
	Return the active pinning policy. More...
HostAllocationPolicy	select_on_container_copy_construction () const
	Use default allocator for copy (same as construct+copy)

Member Function Documentation

void gmx::HostAllocationPolicy::free ( void *  buffer ) const

noexcept

Free the memory, after unpinning (if appropriate).

Parameters

buffer

Memory pointer previously returned from gmx::HostAllocationPolicy::malloc()

Note

This routine should only be called with pointers obtained from gmx:HostAllocationPolicy::malloc(), and absolutely not any pointers obtained the system malloc().

Does not throw.

void * gmx::HostAllocationPolicy::malloc ( std::size_t  bytes ) const

noexcept

Allocate and perhaps pin page-aligned memory suitable for e.g. GPU transfers.

Before attempting to allocate, unpin() is called. After a successful allocation, pin() is called. (Whether these do things depends on the PinningPolicy that is in effect.)

Parameters

bytes

Amount of memory (bytes) to allocate. It is valid to ask for 0 bytes, which will return a non-null pointer that is properly aligned and padded (but that you should not use).

Returns

Valid pointer if the allocation+optional pinning worked, otherwise nullptr.

Note

Memory allocated with this routine must be released with gmx::HostAllocationPolicy::free(), and absolutely not the system free().

Does not throw.

PinningPolicy gmx::HostAllocationPolicy::pinningPolicy ( ) const

inline

Return the active pinning policy.

Does not throw.

---

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

• src/gromacs/gpu_utils/hostallocator.h
• src/gromacs/gpu_utils/hostallocator.cpp