HUGECTL(8)

💅 HUGECTL(8) — control policy for backing text, data and malloc() with hugepages 🫶

okay so bestie, this is hugectl from the System Manager's Manual, section 8, and honestly? it's giving "tiny launcher, enormous power" ✨. it's a whole little wrapper that makes your programs use hugepages, and if you've never met a hugepage: hi, they're the big chunky memory pages that save you from TLB misses 💀.

🌸 NAME 🌸

hugectl — Control policy for backing text, data and malloc() with hugepages

✨ SYNOPSIS ✨

hugectl [options] command {arguments}

🦋 DESCRIPTION 🦋

hugectl runs processes with a specific policy for backing memory regions with hugepages. the way that hugepages just hit different is for apps that use large amounts of address space and suffer a performance hit due to TLB misses. policy is enforced by libhugetlbfs, and hugectl configures the environment based on the options you hand it. and like — how do you even know if it's worth it? you can use wall-clock time or oprofile to figure out whether hugepages are actually giving you a performance benefit or not. no cap 🔍.

to effectively back text/data, the target process must be relinked so the ELF segments are aligned on a hugepage boundary. also, the library supports way more options for controlling memory regions than hugectl exposes — see the libhugetlbfs manual page for the full tea, iykyk 🍵.

💖 the ones that decide what memory regions get backed by hugepages

• --text[=<size>], --data[=<size>], --bss[=<size>] — back the text, data or BSS segments with hugepages, optionally with pages of the specified size. for this to actually be effective, the process must be relinked as described in the HOWTO so the ELF segments line up. you can partially back segments using the HUGETLB_FORCE_ELMAP environment variable, as described in the libhugetlbfs manual page 👑.
• --heap[=<size>] — use the glibc morecore hook to back malloc() with hugepages, optionally with pages of the specified size. heads up though: this does not affect brk() segments, and applications that use custom allocators potentially do not use hugepages for their heap even with this option specified 🙈.
• --shm — this option overrides shmget() to back shared memory regions with hugepages if possible. segment size requests will be aligned to fit to the default hugepage size region 🎀.
• --share-text — request that multiple application instances share text segments that are backed with huge pages. this option sets the environment variable HUGETLB_SHARE to 1. sharing is caring fr fr 🫶.
• --thp — align heap regions to huge page size for promotion by khugepaged. for more information on transparent huge pages, see linux-2.6/Documentation/transhuge.txt ✨.

🎀 the ones that change how hugectl itself behaves

• --no-preload — disable any pre-loading of the libhugetlbfs library. this may be necessary if only the heap is being backed by hugepages and the application is already linked against the library. hugectl may pre-load the library by mistake, and this option prevents that 💀.
• --force-preload — force pre-loading of the libhugetlbfs library. this is the one you want when the segments of the binary are aligned to the hugepage boundary of interest but the binary is not linked against libhugetlbfs. super useful on PPC64, where binaries are aligned to 64K as required by the ABI and the kernel is using a 4K base pagesize 🔥.
• --no-reserve — by default, huge pages are reserved at mmap() time so future faults will succeed. this avoids unexpected application but some applications depend on memory overcommit to create large sparse mappings. for this type of application, this switch will create huge page backed mappings without a reservation if the kernel is recent enough to make this operation safe.

⚠️ use this option with extreme care — in the event huge pages are not available when the mapping is faulted, the application will be killed. like, literally gone. 💀

• --dry-run — instead of running the process, the hugectl utility will describe what environment variables it set for libhugetlbfs. this is useful if additional environment variables are to be set and a launcher shell script is being developed 🧚.
• --library-use-path — by default, hugectl will use the version of libhugetlbfs it was installed with, even if this is not in the LD_LIBRARY_PATH environment. using this option forces hugectl to use the version of libhugetlbfs installed in the library system path 🌈.
• --library-path <path> — this option forces hugectl to use the libhugetlbfs libraries within the given prefix.

⭐ the ones that control how chatty libhugetlbfs is

• --verbose <level>, -v — the default value for the verbosity level is 1, and the range of the value can be set with --verbose from 0 to 99. the higher the value, the more verbose the library will be. 0 is quiet and 3 will output much debugging information. the verbosity level is increased by one each time -v is specified 📢.
• -q — the -q option will decrease the verbosity level by 1 each time it is specified, to a minimum of 0 🤫.

👀 SEE ALSO 👀

oprofile(1), hugeadm(7), libhugetlbfs(7)

👑 AUTHORS 👑

libhugetlbfs was written by various people on the libhugetlbfs-devel mailing list 💜.

and that's the whole page, bestie!! 🎀 this one's dated October 10, 2008, it lives in the System Manager's Manual as HUGECTL(8), and you absolutely ate by reading to the end. go hugepage something. periodt. 💅✨