NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS
NOTES
UTILS
ENVIRONMENT
SYSTEM CONFIGURATION
KNOWN ISSUES
COPYRIGHT
SEE ALSO
hbwmalloc - The high bandwidth memory interface.
Note: hbwmalloc.h functionality is considered as a stable API (STANDARD API).
#include <hbwmalloc.h>
Link with -lmemkind
int hbw_check_available(void);
void* hbw_malloc(size_t size);
void* hbw_calloc(size_t nmemb, size_t size);
void* hbw_realloc (void *ptr, size_t size);
void hbw_free(void *ptr);
size_t hbw_malloc_usable_size(void *ptr);
int hbw_posix_memalign(void **memptr, size_t alignment, size_t size);
int hbw_posix_memalign_psize(void **memptr, size_t alignment, size_t size, hbw_pagesize_t pagesize);
hbw_policy_t hbw_get_policy(void);
int hbw_set_policy(hbw_policy_t mode);
int hbw_verify_memory_region(void *addr, size_t size, int flags);
hbw_check_available()
hbw_malloc()
hbw_malloc()
returns NULL.hbw_calloc()
hbw_malloc()
with an argument of nmemb * size,
with the exception that the allocated memory is explicitly
initialized to zero bytes. If nmemb or size is 0, then
hbw_calloc()
returns NULL.hbw_realloc()
hbw_realloc()
may move the memory allocation,
resulting in a different return value than ptr.hbw_realloc()
function behaves
identically to hbw_malloc()
for the specified size. If
size is equal to zero and ptr is not NULL, then the call
is equivalent to hbw_free(ptr)
and NULL is returned. The
address ptr, if not NULL, was returned by a previous call
to hbw_malloc()
, hbw_calloc()
, hbw_realloc()
or
hbw_posix_memalign()
. Otherwise, or if hbw_free(ptr)
was
called before, undefined behavior occurs.
Note: hbw_realloc()
cannot be used with a pointer
returned by hbw_posix_memalign_psize()
.hbw_free()
hbw_malloc()
,
hbw_calloc()
, hbw_realloc()
, hbw_posix_memalign()
or
hbw_posix_memalign_psize()
. Otherwise, if hbw_free(ptr)
was
called before, undefined behavior occurs.hbw_malloc_usable_size()
hbw_malloc()
, hbw_calloc()
, hbw_realloc()
,
hbw_posix_memalign()
, or hbw_posix_memalign_psize()
.hbw_posix_memalign()
hbw_posix_memalign()
returns 0, with a NULL returned in
memptr. See the ERRORS section for other
possible return values.hbw_posix_memalign_psize()
HBW_PAGESIZE_4KB
The four kilobyte page size option. Note that with transparent
huge pages enabled these allocations may be promoted by the
operating system to two megabyte pages.
HBW_PAGESIZE_2MB
The two megabyte page size option.
Note: This page size requires huge pages configuration
described in the SYSTEM CONFIGURATION
section.
Note: HBW_PAGESIZE_2MB, option is not supported with the HBW_POLICY_INTERLEAVE policy which is described below.
hbw_set_policy()
hbw_malloc()
, hbw_calloc()
, hbw_realloc()
,
hbw_posix_memalign()
, or hbw_posix_memalign_psize()
functions.
Note: If the policy is not set, then
HBW_POLICY_PREFERRED will be used by default.HBW_POLICY_BIND
If insufficient high bandwidth memory from the nearest NUMA
node is available to satisfy a request, the allocated pointer
is set to NULL and errno is set to ENOMEM. If
insufficient high bandwidth memory pages are available at the
fault time the Out Of Memory (OOM) Killer is triggered. Note
that pages are faulted exclusively from the high bandwidth NUMA
node nearest at the time of allocation, not at the time of
fault.
HBW_POLICY_BIND_ALL
If insufficient high bandwidth memory is available to satisfy a
request, the allocated pointer is set to NULL and errno is
set to ENOMEM. If insufficient high bandwidth memory pages
are available at the fault time the Out Of Memory (OOM)
Killer is triggered. Note that pages are faulted from the high
bandwidth NUMA nodes. Nearest NUMA node is selected at the time
of the page fault.
HBW_POLICY_PREFERRED
If insufficient memory is available from the high bandwidth
NUMA node closest at the allocation time, fall back to standard
memory (default) with the smallest NUMA distance.
HBW_POLICY_INTERLEAVE
Interleave faulted pages from across all high bandwidth NUMA
nodes using standard size pages (the Transparent Huge Page
feature is disabled).
hbw_get_policy()
hbw_verify_memory_region()
hbw_get_policy()
returns HBW_POLICY_BIND, HBW_POLICY_BIND_ALL,
HBW_POLICY_PREFERRED or HBW_POLICY_INTERLEAVE which represents
the current high bandwidth policy. hbw_free()
do not have a return value.
hbw_malloc()
, hbw_calloc()
and hbw_realloc()
return the pointer to
the allocated memory or NULL if the request fails. hbw_posix_memalign()
,
hbw_posix_memalign_psize()
and hbw_set_policy()
return zero on success
and return an error code as described in the ERRORS section
below on failure.
Error codes described here are the POSIX standard error codes as defined in <errno.h>
hbw_check_available()
hbw_posix_memalign()
and hbw_posix_memalign_psize()
If the alignment parameter is not a power of two, or was not
a multiple of sizeof(void)*, then EINVAL is returned.
If the policy and pagesize combination is unsupported then
EINVAL is returned. If there was insufficient memory to
satisfy the request then ENOMEM is returned.
hbw_set_policy()
hbw_verify_memory_region()
The <hbwmalloc.h> file defines the external functions and enumerations for the hbwmalloc library. These interfaces define a heap manager that targets high bandwidth memory numa nodes.
numa_parse_nodestring()
for parsing, so the syntax
described in the numa(3)
man page for this routine applies,
for example: 1-3,5 is a valid setting.Note: If the MEMKIND_HEAP_MANAGER is not set then the jemalloc heap manager will be used by default.
sudo sysctl vm.nr_hugepages=<number_of_hugepages>
.
More information can be found here:
https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txtInterfaces for obtaining 2MB (HUGETLB) memory need allocated huge pages in the kernel’s huge page pool.
Copyright (C) 2014 - 2022 Intel Corporation. All rights reserved.
malloc(3), numa(3), jemalloc(3), memkind(3)
The contents of this web site and the associated GitHub repositories are BSD-licensed open source.