Gromacs  2023.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Types | Public Member Functions
gmx::HostAllocationPolicy Class Reference

#include <gromacs/gpu_utils/hostallocator.h>


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

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)
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

Free the memory, after unpinning (if appropriate).

bufferMemory pointer previously returned from gmx::HostAllocationPolicy::malloc()
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

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

bytesAmount 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).
Valid pointer if the allocation+optional pinning worked, otherwise nullptr.
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

Return the active pinning policy.

Does not throw.

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