| HBWMALLOC(3) | HBWMALLOC | HBWMALLOC(3) |
hbwmalloc - The high bandwidth memory interface
Note: hbwmalloc.h functionality is considered as 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() returns zero if high bandwidth memory is available or an error code described in the ERRORS section if not.
hbw_malloc() allocates size bytes of uninitialized high bandwidth memory. The allocated space is suitably aligned (after possible pointer coercion) for storage of any type of object. If size is zero then hbw_malloc() returns NULL.
hbw_calloc() allocates space for nmemb objects in high bandwidth memory, each size bytes in length. The result is identical to calling 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() changes the size of the previously allocated high bandwidth memory referenced by ptr to size bytes. The contents of the memory remain unchanged up to the lesser of the new and old sizes. If the new size is larger, the contents of the newly allocated portion of the memory are undefined. Upon success, the memory referenced by ptr is freed and a pointer to the newly allocated high bandwidth memory is returned.
Note: hbw_realloc() may move the memory allocation, resulting in a different return value than ptr.
If ptr is NULL, the 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() causes the allocated memory referenced by ptr to be made available for future allocations. If ptr is NULL, no action occurs. The address ptr, if not NULL, must have been returned by a previous call to 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() returns the number of usable bytes in the block pointed to by ptr, a pointer to a block of memory allocated by hbw_malloc(), hbw_calloc(), hbw_realloc(), hbw_posix_memalign(), or hbw_posix_memalign_psize().
hbw_posix_memalign() allocates size bytes of high bandwidth memory such that the allocation's base address is an even multiple of alignment, and returns the allocation in the value pointed to by memptr. The requested alignment must be a power of 2 at least as large as sizeof(void*). If size is 0, then hbw_posix_memalign() returns 0, with a NULL returned in memptr.
hbw_posix_memalign_psize() allocates size bytes of high bandwidth memory such that the allocation's base address is an even multiple of alignment, and returns the allocation in the value pointed to by memptr. The requested alignment must be a power of 2 at least as large as sizeof(void*). The memory will be allocated using pages determined by the pagesize variable which may be one of the following enumerated values:
Note: HBW_PAGESIZE_2MB, HBW_PAGESIZE_1GB and HBW_PAGESIZE_1GB_STRICT options are not supported with HBW_POLICY_INTERLEAVE policy.
hbw_get_policy() returns the current fallback policy when insufficient high bandwidth memory is available.
hbw_set_policy() sets the current fallback policy. The
policy can be modified only once in the lifetime of an application and
before calling hbw_malloc(), hbw_calloc(),
hbw_realloc(), hbw_posix_memalign(), or
hbw_posix_memalign_psize() function.
Note: If the policy is not set, than HBW_POLICY_PREFERRED will
be used by default.
hbw_verify_memory_region() verifies if memory region fully falls into high bandwidth memory. Returns 0 if memory address range from addr to addr + size is allocated in high bandwidth memory, -1 if any fragment of memory was not backed by high bandwidth memory (e.g. when memory is not initialized) or one of error codes described in ERRORS section.
Using this function in production code may result in serious performance penalty.
The Flags argument may include optional flags that modify function behavior:
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 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.
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.
Note: If the MEMKIND_HEAP_MANAGER is not set then the jemalloc heap manager will be used by default.
Interfaces for obtaining 2MB (HUGETLB) memory need allocated huge pages in the kernel's huge page pool.
Copyright (C) 2014 - 2020 Intel Corporation. All rights reserved.
malloc(3), numa(3), numactl(8), mbind(2), mmap(2), move_pages(2), jemalloc(3), memkind(3)
| 2015-03-31 | Intel Corporation |