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