|
Packit Service |
724aca |
.\"
|
|
Packit Service |
724aca |
.\" Copyright (C) 2019 Intel Corporation.
|
|
Packit Service |
724aca |
.\" All rights reserved.
|
|
Packit Service |
724aca |
.\"
|
|
Packit Service |
724aca |
.\" Redistribution and use in source and binary forms, with or without
|
|
Packit Service |
724aca |
.\" modification, are permitted provided that the following conditions are met:
|
|
Packit Service |
724aca |
.\" 1. Redistributions of source code must retain the above copyright notice(s),
|
|
Packit Service |
724aca |
.\" this list of conditions and the following disclaimer.
|
|
Packit Service |
724aca |
.\" 2. Redistributions in binary form must reproduce the above copyright notice(s),
|
|
Packit Service |
724aca |
.\" this list of conditions and the following disclaimer in the documentation
|
|
Packit Service |
724aca |
.\" and/or other materials provided with the distribution.
|
|
Packit Service |
724aca |
.\"
|
|
Packit Service |
724aca |
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY EXPRESS
|
|
Packit Service |
724aca |
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
Packit Service |
724aca |
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
|
|
Packit Service |
724aca |
.\" EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
Packit Service |
724aca |
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
Packit Service |
724aca |
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
Packit Service |
724aca |
.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
Packit Service |
724aca |
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
|
|
Packit Service |
724aca |
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
|
|
Packit Service |
724aca |
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
Packit Service |
724aca |
.\"
|
|
Packit Service |
724aca |
.TH "MEMKINDALLOCATOR" 3 "2019-09-24" "Intel Corporation" "MEMKINDALLOCATOR" \" -*- nroff -*-
|
|
Packit Service |
724aca |
.SH "NAME"
|
|
Packit Service |
724aca |
libmemkind::static_kind::allocator<T> \- The C++ allocator compatible with the C++ standard library allocator concepts
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BR Note:
|
|
Packit Service |
724aca |
.I memkind_allocator.h
|
|
Packit Service |
724aca |
functionality is considered as stable API (STANDARD API).
|
|
Packit Service |
724aca |
.SH "SYNOPSIS"
|
|
Packit Service |
724aca |
.nf
|
|
Packit Service |
724aca |
.B #include <memkind_allocator.h>
|
|
Packit Service |
724aca |
.sp
|
|
Packit Service |
724aca |
.B Link with -lmemkind
|
|
Packit Service |
724aca |
.sp
|
|
Packit Service |
724aca |
.BI "libmemkind::static_kind::allocator(libmemkind::kinds " "kind" );
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BI "template <typename U> libmemkind::static_kind::allocator<T>::allocator(const libmemkind::static_kind::allocator<U>&)" " "noexcept;
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BI "template <typename U> libmemkind::static_kind::allocator(const allocator<U>&& " "other" ) " "noexcept;
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BI "libmemkind::static_kind::allocator<T>::~allocator();
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BI "T *libmemkind::static_kind::allocator<T>::allocate(std::size_t " "n" ) " "const;
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BI "void libmemkind::static_kind::allocator<T>::deallocate(T " "*p" ", std::size_t " "n" ) " "const;
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BI "template <class U, class... Args> void libmemkind::static_kind::allocator<T>::construct(U " "*p" ", Args... " "args" ) " "const;
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BI "void libmemkind::static_kind::allocator<T>::destroy(T " "*p" ) " "const;
|
|
Packit Service |
724aca |
.fi
|
|
Packit Service |
724aca |
.SH "DESCRIPTION"
|
|
Packit Service |
724aca |
The
|
|
Packit Service |
724aca |
.BR libmemkind::static_kind::allocator<T>
|
|
Packit Service |
724aca |
is intended to be used with STL containers to allocate from static kinds memory. Memory management is based on memkind library. Refer
|
|
Packit Service |
724aca |
.BR memkind (3)
|
|
Packit Service |
724aca |
man page for more details.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
The
|
|
Packit Service |
724aca |
.BR libmemkind::kinds
|
|
Packit Service |
724aca |
specifies allocator static kinds of memory, representing type of memory which offers different characteristics. The available types of allocator kinds of memory:
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::DEFAULT
|
|
Packit Service |
724aca |
Default allocation using standard memory and default page size.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HUGETLB
|
|
Packit Service |
724aca |
Allocate from standard memory using huge pages. Note: This kind requires huge pages configuration described in
|
|
Packit Service |
724aca |
.B SYSTEM CONFIGURATION
|
|
Packit Service |
724aca |
section.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::INTERLEAVE
|
|
Packit Service |
724aca |
Allocate pages interleaved across all NUMA nodes with transparent huge pages disabled.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW
|
|
Packit Service |
724aca |
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
|
|
Packit Service |
724aca |
.IR "NULL" .
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_ALL
|
|
Packit Service |
724aca |
Same as
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW
|
|
Packit Service |
724aca |
except decision regarding closest NUMA node is postponed until the time of first write.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_HUGETLB
|
|
Packit Service |
724aca |
Same as
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW
|
|
Packit Service |
724aca |
except the allocation is backed by huge pages. Note: This kind requires huge pages configuration described in
|
|
Packit Service |
724aca |
.B SYSTEM CONFIGURATION
|
|
Packit Service |
724aca |
section.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_ALL_HUGETLB
|
|
Packit Service |
724aca |
Combination of
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_ALL
|
|
Packit Service |
724aca |
and
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_HUGETLB
|
|
Packit Service |
724aca |
properties. Note: This kind requires huge pages configuration described in
|
|
Packit Service |
724aca |
.B SYSTEM CONFIGURATION
|
|
Packit Service |
724aca |
section.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_PREFERRED
|
|
Packit Service |
724aca |
Same as
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW
|
|
Packit Service |
724aca |
except that if there is not enough high bandwidth memory to satisfy the request, the allocation will fall back on standard memory.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_PREFERRED_HUGETLB
|
|
Packit Service |
724aca |
Same as
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_PREFERRED
|
|
Packit Service |
724aca |
except the allocation is backed by huge pages. Note: This kind requires huge pages configuration described in
|
|
Packit Service |
724aca |
.B SYSTEM CONFIGURATION
|
|
Packit Service |
724aca |
section.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW_INTERLEAVE
|
|
Packit Service |
724aca |
Same as
|
|
Packit Service |
724aca |
.B libmemkind::kinds::HBW
|
|
Packit Service |
724aca |
except that the pages that support the allocation are interleaved across all high bandwidth nodes and transparent huge pages are disabled.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::REGULAR
|
|
Packit Service |
724aca |
Allocate from regular memory using the default page size. Regular means general purpose memory from the NUMA nodes containing CPUs.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::DAX_KMEM
|
|
Packit Service |
724aca |
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,
|
|
Packit Service |
724aca |
.I errno
|
|
Packit Service |
724aca |
is set to
|
|
Packit Service |
724aca |
.B ENOMEM
|
|
Packit Service |
724aca |
and the allocated pointer is set to
|
|
Packit Service |
724aca |
.IR "NULL" .
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::DAX_KMEM_ALL
|
|
Packit Service |
724aca |
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,
|
|
Packit Service |
724aca |
.I errno
|
|
Packit Service |
724aca |
is set to
|
|
Packit Service |
724aca |
.B ENOMEM
|
|
Packit Service |
724aca |
and the allocated pointer is set to
|
|
Packit Service |
724aca |
.IR "NULL" .
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.B libmemkind::kinds::DAX_KMEM_PREFERRED
|
|
Packit Service |
724aca |
Same as
|
|
Packit Service |
724aca |
.B libmemkind::kinds::DAX_KMEM
|
|
Packit Service |
724aca |
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.
|
|
Packit Service |
724aca |
.BR Note:
|
|
Packit Service |
724aca |
For this kind, the allocation will not succeed if two or more
|
|
Packit Service |
724aca |
persistent memory NUMA nodes are in the same shortest distance to the same CPU on which process is eligible to run.
|
|
Packit Service |
724aca |
Check on that eligibility is done upon starting the application.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
All public member types and functions correspond to standard library allocator concepts and definitions. The current implementation supports C++11 standard.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
Template arguments:
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.I T
|
|
Packit Service |
724aca |
is an object type aliased by value_type.
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.I U
|
|
Packit Service |
724aca |
is an object type.
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.BR Note:
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.BI "T *libmemkind::static_kind::allocator<T>::allocate(std::size_t " "n")
|
|
Packit Service |
724aca |
allocates memory using
|
|
Packit Service |
724aca |
.BR memkind_malloc ().
|
|
Packit Service |
724aca |
Throw
|
|
Packit Service |
724aca |
.I std::bad_alloc
|
|
Packit Service |
724aca |
when:
|
|
Packit Service |
724aca |
.RS
|
|
Packit Service |
724aca |
.I n
|
|
Packit Service |
724aca |
= 0
|
|
Packit Service |
724aca |
.RE
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
.RS
|
|
Packit Service |
724aca |
.br
|
|
Packit Service |
724aca |
or there is not enough memory to satisfy the request.
|
|
Packit Service |
724aca |
.RE
|
|
Packit Service |
724aca |
.PP
|
|
Packit Service |
724aca |
.BI "libmemkind::static_kind::allocator<T>::deallocate(T " "*p" ", std::size_t " "n")
|
|
Packit Service |
724aca |
deallocates memory associated with pointer returned by
|
|
Packit Service |
724aca |
.BR allocate ()
|
|
Packit Service |
724aca |
using
|
|
Packit Service |
724aca |
.BR memkind_free ().
|
|
Packit Service |
724aca |
.SH "SYSTEM CONFIGURATION"
|
|
Packit Service |
724aca |
Interfaces for obtaining 2MB (HUGETLB) memory need allocated
|
|
Packit Service |
724aca |
huge pages in the kernel's huge page pool.
|
|
Packit Service |
724aca |
.TP
|
|
Packit Service |
724aca |
.B HUGETLB (huge pages)
|
|
Packit Service |
724aca |
Current number of "persistent" huge pages can be read from
|
|
Packit Service |
724aca |
.I /proc/sys/vm/nr_hugepages
|
|
Packit Service |
724aca |
file.
|
|
Packit Service |
724aca |
Proposed way of setting hugepages is:
|
|
Packit Service |
724aca |
.BR "sudo sysctl vm.nr_hugepages=<number_of_hugepages>" .
|
|
Packit Service |
724aca |
More information can be found here:
|
|
Packit Service |
724aca |
.UR https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt
|
|
Packit Service |
724aca |
.UE
|
|
Packit Service |
724aca |
.SH "COPYRIGHT"
|
|
Packit Service |
724aca |
Copyright (C) 2019 Intel Corporation. All rights reserved.
|
|
Packit Service |
724aca |
.SH "SEE ALSO"
|
|
Packit Service |
724aca |
.BR memkind (3)
|