Gromacs  2020.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Types | Public Member Functions
gmx::Allocator< T, AllocationPolicy > Class Template Reference

#include <gromacs/utility/allocator.h>

Inherits AllocationPolicy.

Description

template<class T, typename AllocationPolicy>
class gmx::Allocator< T, AllocationPolicy >

Policy-based memory allocator.

Template Parameters
TType of objects to allocate
AllocationPolicyPolicy of (matching) allocation and deallocation functions.

This class can be used for the optional allocator template parameter in standard library containers. It must be configured with both the type of object to allocate, and an AllocationPolicy which effectively wraps a matching pair of malloc and free functions. This permits implementing a family of related allocators e.g. with SIMD alignment, GPU host-side page locking, or perhaps both, in a way that preserves a common programming interface and duplicates minimal code.

AllocationPolicy is used as a base class, so that if AllocationPolicy is stateless, then the empty base optimization will ensure that Allocation is also stateless, and objects made with the Allocator will incur no size penalty. (Embedding an AllocationPolicy object incurs a size penalty always, even if the object is empty.) Normally a stateless allocator will be used.

However, an AllocationPolicy with state might be desirable for simplifying writing code that needs to allocate suitably for a transfer to a GPU. That code needs to specify an Allocator that can do the right job, which can be stateless. However, if we have code that will not know until run time whether a GPU transfer will occur, then the allocator needs to be aware of the state. That will increase the size of a container that uses the stateful allocator.

Exceptions
std::bad_allocInstead of a GROMACS exception object, we throw the standard one on allocation failures to make it as compatible as possible with the errors expected by code using the standard library containers.

Public Types

typedef T value_type
 Type of allocated elements.
 

Public Member Functions

 Allocator ()=default
 Constructor. More...
 
 Allocator (const AllocationPolicy &p)
 Constructor to accept an AllocationPolicy. More...
 
value_typeallocate (std::size_t n, typename std::allocator< void >::const_pointer hint=nullptr)
 Do the actual memory allocation. More...
 
void deallocate (value_type *p, std::size_t n)
 Release memory. More...
 
template<class T2 , class A = AllocationPolicy, typename = std::enable_if_t<std::is_empty<A>::value>>
bool operator== (const Allocator< T2, AllocationPolicy > &) const
 Return true if two allocators are identical. More...
 
template<class T2 >
bool operator!= (const Allocator< T2, AllocationPolicy > &rhs) const
 Return true if two allocators are different. More...
 

Constructor & Destructor Documentation

template<class T , typename AllocationPolicy >
gmx::Allocator< T, AllocationPolicy >::Allocator ( )
default

Constructor.

No constructor can be auto-generated in the presence of any user-defined constructor, but we want the default constructor.

template<class T , typename AllocationPolicy >
gmx::Allocator< T, AllocationPolicy >::Allocator ( const AllocationPolicy &  p)
inline

Constructor to accept an AllocationPolicy.

This is useful for AllocationPolicies with state.

Member Function Documentation

template<class T , typename AllocationPolicy >
value_type* gmx::Allocator< T, AllocationPolicy >::allocate ( std::size_t  n,
typename std::allocator< void >::const_pointer  hint = nullptr 
)
inline

Do the actual memory allocation.

Parameters
nNumber of elements of type T to allocate. n can be 0 bytes, which will return a non-null properly aligned and padded pointer that should not be used.
hintOptional value returned from previous call to allocate. For now this is not used.
Returns
Pointer to allocated memory
Exceptions
std::bad_allocif the allocation fails.
template<class T , typename AllocationPolicy >
void gmx::Allocator< T, AllocationPolicy >::deallocate ( value_type p,
std::size_t  n 
)
inline

Release memory.

Parameters
pPointer to previously allocated memory returned from allocate()
nnumber of objects previously passed to allocate()
template<class T , typename AllocationPolicy >
template<class T2 >
bool gmx::Allocator< T, AllocationPolicy >::operator!= ( const Allocator< T2, AllocationPolicy > &  rhs) const
inline

Return true if two allocators are different.

Parameters
rhsOther allocator.

This is a member function of the left-hand-side allocator.

template<class T , typename AllocationPolicy >
template<class T2 , class A = AllocationPolicy, typename = std::enable_if_t<std::is_empty<A>::value>>
bool gmx::Allocator< T, AllocationPolicy >::operator== ( const Allocator< T2, AllocationPolicy > &  ) const
inline

Return true if two allocators are identical.

This is a member function of the left-hand-side allocator. Always true for stateless polcies. Has to be defined in the policy for stateful policies. FUTURE: Can be removed with C++17 (is_always_equal)


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