GET_HUGEPAGE_REGION(3)

💖 GET_HUGEPAGE_REGION(3) 💖

okay bestie, this is a page from the Library Functions Manual and it's about get_hugepage_region and free_hugepage_region — the duo that hands you memory backed by hugepages when it can. let's get into it 🫶

✨ NAME ✨

get_hugepage_region, free_hugepage_region — the iconic pair that allocates and frees regions of memory that use hugepages where possible 💅

🌸 SYNOPSIS 🌸

#include <hugetlbfs.h>

void *get_hugepage_region(size_t len, ghr_t flags);
void free_hugepage_region(void *ptr);

like. two functions. one header. so clean ✨

🦋 DESCRIPTION 🦋

so get_hugepage_region() allocates a memory region that's len bytes in size, backed by hugepages. why do you care? bc hugepages may be of benefit to applications that use large amounts of address space and are suffering a performance hit due to TLB misses 😭. and how do you even know if it's helping? well — wall-clock time or oprofile can be used to determine if there's a performance benefit from using hugepages or not. vibe check your workload, basically.

now, unlike get_huge_pages(), len does not have to be hugepage-aligned — although memory may be wasted due to alignment. and the caller may also specify that base pages be used in the event there are no hugepages available. flexible queen behavior 👑

the flags argument changes the behaviour of the function. flags may be or'd together. so:

• GHR_FALLBACK — use base pages if there are an insufficient number of huge pages.
• GHR_STRICT — use hugepages or return NULL. no backup plan, no safety net, all or nothing 💀
• GHR_COLOR — when specified, bytes that would be wasted due to alignment are used to color the buffer by offsetting it by a random cacheline within the hugepage. this avoids a performance problem whereby multiple buffers use the same cache lines at the same offsets. so if it is not important that the start of the buffer be page-aligned, specify this flag. it's giving ✨ chaos but productive ✨
• GHR_DEFAULT — the library chooses a sensible combination of flags for allocating a region of memory. the current default is:

GHR_FALLBACK | GHR_COLOR

and then free_hugepage_region() frees a region of memory allocated by get_hugepage_region().

🚨 okay listen: the behaviour of the function if another pointer is used, valid or otherwise, is undefined. undefined. so don't be cute with it, bestie. pass the pointer you got. periodt.

🌈 RETURN VALUE 🌈

• on success, a pointer is returned for to the allocated memory 🎀
• on error, NULL is returned.
• errno will be set based on what the failure of mmap() was due to.

👑 SEE ALSO 👑

• oprofile(1)
• gethugepagesize(3)
• get_huge_pages(3)
• libhugetlbfs(7)

go read them, iykyk 📚

💜 AUTHORS 💜

libhugetlbfs was written by various people on the libhugetlbfs-devel mailing list. a whole group chat of legends fr fr 🫶

and that's the whole page, bestie!! this one's dated November 7, 2008 and it comes to you from libhugetlbfs — so if you're reading this on a modern system, just know the source and version are doing their little archival moment 💖 stay hugepage-aligned (or don't, GHR_COLOR says it's fine) and slay 🧚✨