.\"

.\" Copyright (C) 2019 Intel Corporation.

.\" All rights reserved.

.\"

.\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions are met:

.\" 1. Redistributions of source code must retain the above copyright notice(s),

.\"    this list of conditions and the following disclaimer.

.\" 2. Redistributions in binary form must reproduce the above copyright notice(s),

.\"    this list of conditions and the following disclaimer in the documentation

.\"    and/or other materials provided with the distribution.

.\"

.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY EXPRESS

.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO

.\" EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY DIRECT, INDIRECT,

.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE

.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF

.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

.\"

.TH "MEMKINDALLOCATOR" 3 "2019-09-24" "Intel Corporation" "MEMKINDALLOCATOR" \" -*- nroff -*-

.SH "NAME"

libmemkind::static_kind::allocator<T> \- The C++ allocator compatible with the C++ standard library allocator concepts

.br

.BR Note:

.I memkind_allocator.h

functionality is considered as stable API (STANDARD API).

.SH "SYNOPSIS"

.nf

.B #include <memkind_allocator.h>

.sp

.B Link with -lmemkind

.sp

.BI "libmemkind::static_kind::allocator(libmemkind::kinds " "kind" );

.br

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

.br

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

.br

.BI "libmemkind::static_kind::allocator<T>::~allocator();

.br

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

.br

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

.br

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

.br

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

.fi

.SH "DESCRIPTION"

The

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

.BR memkind (3)

man page for more details.

.PP

The

.BR libmemkind::kinds

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

.PP

.B libmemkind::kinds::DEFAULT

Default allocation using standard memory and default page size.

.PP

.B libmemkind::kinds::HUGETLB

Allocate from standard memory using huge pages. Note: This kind requires huge pages configuration described in

.B SYSTEM CONFIGURATION

section.

.PP

.B libmemkind::kinds::INTERLEAVE

Allocate pages interleaved across all NUMA nodes with transparent huge pages disabled.

.PP

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

.IR "NULL" .

.PP

.B libmemkind::kinds::HBW_ALL

Same as

.B libmemkind::kinds::HBW

except decision regarding closest NUMA node is postponed until the time of first write.

.PP

.B libmemkind::kinds::HBW_HUGETLB

Same as

.B libmemkind::kinds::HBW

except the allocation is backed by huge pages. Note: This kind requires huge pages configuration described in

.B SYSTEM CONFIGURATION

section.

.PP

.B libmemkind::kinds::HBW_ALL_HUGETLB

Combination of

.B libmemkind::kinds::HBW_ALL

and

.B libmemkind::kinds::HBW_HUGETLB

properties. Note: This kind requires huge pages configuration described in

.B SYSTEM CONFIGURATION

section.

.PP

.B libmemkind::kinds::HBW_PREFERRED

Same as

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

.PP

.B libmemkind::kinds::HBW_PREFERRED_HUGETLB

Same as

.B libmemkind::kinds::HBW_PREFERRED

except the allocation is backed by huge pages. Note: This kind requires huge pages configuration described in

.B SYSTEM CONFIGURATION

section.

.PP

.B libmemkind::kinds::HBW_INTERLEAVE

Same as

.B libmemkind::kinds::HBW

except that the pages that support the allocation are interleaved across all high bandwidth nodes and transparent huge pages are disabled.

.PP

.B libmemkind::kinds::REGULAR

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

.PP

.B 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,

.I errno

is set to

.B ENOMEM

and the allocated pointer is set to

.IR "NULL" .

.PP

.B 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,

.I errno

is set to

.B ENOMEM

and the allocated pointer is set to

.IR "NULL" .

.PP

.B libmemkind::kinds::DAX_KMEM_PREFERRED

Same as

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

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

.PP

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

.PP

Template arguments:

.br

.I T

is an object type aliased by value_type.

.br

.I U

is an object type.

.PP

.BR Note:

.br

.BI "T *libmemkind::static_kind::allocator<T>::allocate(std::size_t " "n")

allocates memory using

.BR memkind_malloc ().

Throw

.I std::bad_alloc

when:

.RS

.I n

= 0

.RE

.br

.RS

.br

or there is not enough memory to satisfy the request.

.RE

.PP

.BI "libmemkind::static_kind::allocator<T>::deallocate(T " "*p" ", std::size_t " "n")

deallocates memory associated with pointer returned by

.BR allocate ()

using

.BR memkind_free ().

.SH "SYSTEM CONFIGURATION"

Interfaces for obtaining 2MB (HUGETLB) memory need allocated

huge pages in the kernel's huge page pool.

.TP

.B HUGETLB (huge pages)

Current number of "persistent" huge pages can be read from

.I /proc/sys/vm/nr_hugepages

file.

Proposed way of setting hugepages is:

.BR "sudo sysctl vm.nr_hugepages=<number_of_hugepages>" .

More information can be found here:

.UR https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt

.UE

.SH "COPYRIGHT"

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

.SH "SEE ALSO"

.BR memkind (3)