NAME¶

libmemkind::static_kind::allocator<T> - The C++ allocator compatible with the C++ standard library allocator concepts
Note: memkind_allocator.h functionality is considered as stable API (STANDARD API).

SYNOPSIS¶

#include <memkind_allocator.h>

Link with -lmemkind

libmemkind::static_kind::allocator(libmemkind::kinds kind);


template <typename U> libmemkind::static_kind::allocator<T>::allocator(const libmemkind::static_kind::allocator<U>&) noexcept;


template <typename U> libmemkind::static_kind::allocator(const allocator<U>&& other) noexcept;


libmemkind::static_kind::allocator<T>::~allocator();


T *libmemkind::static_kind::allocator<T>::allocate(std::size_t n) const;


void libmemkind::static_kind::allocator<T>::deallocate(T *p, std::size_t n) const;


template <class U, class... Args> void libmemkind::static_kind::allocator<T>::construct(U *p, Args... args) const;


void libmemkind::static_kind::allocator<T>::destroy(T *p) const;

DESCRIPTION¶

The libmemkind::static_kind::allocator<T> is intended to be used with STL containers to allocate from static kinds memory. Memory management is based on memkind library. Refer memkind(3) man page for more details.

The libmemkind::kinds specifies allocator static kinds of memory, representing type of memory which offers different characteristics. The available types of allocator kinds of memory:

libmemkind::kinds::DEFAULT Default allocation using standard memory and default page size.

libmemkind::kinds::HUGETLB Allocate from standard memory using huge pages. Note: This kind requires huge pages configuration described in SYSTEM CONFIGURATION section.

libmemkind::kinds::INTERLEAVE Allocate pages interleaved across all NUMA nodes with transparent huge pages disabled.

libmemkind::kinds::HBW Allocate from the closest high bandwidth memory NUMA node at the time of allocation. If there is not enough high bandwidth memory to satisfy the request, errno is set to ENOMEM and the allocated pointer is set to NULL.

libmemkind::kinds::HBW_ALL Same as libmemkind::kinds::HBW except decision regarding closest NUMA node is postponed until the time of first write.

libmemkind::kinds::HBW_HUGETLB Same as libmemkind::kinds::HBW except the allocation is backed by huge pages. Note: This kind requires huge pages configuration described in SYSTEM CONFIGURATION section.

libmemkind::kinds::HBW_ALL_HUGETLB Combination of libmemkind::kinds::HBW_ALL and libmemkind::kinds::HBW_HUGETLB properties. Note: This kind requires huge pages configuration described in SYSTEM CONFIGURATION section.

libmemkind::kinds::HBW_PREFERRED Same as libmemkind::kinds::HBW except that if there is not enough high bandwidth memory to satisfy the request, the allocation will fall back on standard memory.

libmemkind::kinds::HBW_PREFERRED_HUGETLB Same as libmemkind::kinds::HBW_PREFERRED except the allocation is backed by huge pages. Note: This kind requires huge pages configuration described in SYSTEM CONFIGURATION section.

libmemkind::kinds::HBW_INTERLEAVE Same as libmemkind::kinds::HBW except that the pages that support the allocation are interleaved across all high bandwidth nodes and transparent huge pages are disabled.

libmemkind::kinds::REGULAR Allocate from regular memory using the default page size. Regular means general purpose memory from the NUMA nodes containing CPUs.

libmemkind::kinds::DAX_KMEM Allocate from the closest persistent memory NUMA node at the time of allocation. If there is not enough memory in the closest persistent memory NUMA node to satisfy the request, errno is set to ENOMEM and the allocated pointer is set to NULL.

libmemkind::kinds::DAX_KMEM_ALL Allocate from the closest persistent memory NUMA node available at the time of allocation. If there is not enough memory on any of persistent memory NUMA nodes to satisfy the request, errno is set to ENOMEM and the allocated pointer is set to NULL.

libmemkind::kinds::DAX_KMEM_PREFERRED Same as libmemkind::kinds::DAX_KMEM except that if there is not enough memory in the closest persistent memory NUMA node to satisfy the request, the allocation will fall back on other memory NUMA nodes. Note: For this kind, the allocation will not succeed if two or more persistent memory NUMA nodes are in the same shortest distance to the same CPU on which process is eligible to run. Check on that eligibility is done upon starting the application.

All public member types and functions correspond to standard library allocator concepts and definitions. The current implementation supports C++11 standard.

Template arguments:
T is an object type aliased by value_type.
U is an object type.

Note:
T *libmemkind::static_kind::allocator<T>::allocate(std::size_t n) allocates memory using memkind_malloc(). Throw std::bad_alloc when:

libmemkind::static_kind::allocator<T>::deallocate(T *p, std::size_t n) deallocates memory associated with pointer returned by allocate() using memkind_free().

SYSTEM CONFIGURATION¶

Interfaces for obtaining 2MB (HUGETLB) memory need allocated huge pages in the kernel's huge page pool.

HUGETLB (huge pages)

Current number of "persistent" huge pages can be read from /proc/sys/vm/nr_hugepages file. Proposed way of setting hugepages is: sudo sysctl vm.nr_hugepages=<number_of_hugepages>. More information can be found here: https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt

COPYRIGHT¶

Copyright (C) 2019 - 2020 Intel Corporation. All rights reserved.

SEE ALSO¶

memkind(3)