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:
              n = 0
              or there is not enough memory to satisfy the request.

       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 Intel Corporation. All rights reserved.

SEE ALSO

       memkind(3)