Hugetext is an extension of Transparent Huge Pages (THP) that maps the executable sections of applications and dynamic-link libraries (DLLs) to huge pages (typically 2 MB). By reducing instruction Translation Lookaside Buffer (iTLB) misses and increasing iTLB utilization, Hugetext improves performance for workloads with large code segments—databases such as MySQL and PostgreSQL, and large-scale Java applications. Hugetext also helps prevent memory fragmentation and memory bloat, improving overall memory usage.
Performance gains vary by platform and workload. Hugetext has the greatest impact when iTLB pressure is a bottleneck.
Prerequisites
Before you begin, ensure that you have:
An Alibaba Cloud Linux instance running one of the following kernel versions:
Alibaba Cloud Linux 2: kernel
4.19.91-25or laterAlibaba Cloud Linux 3: kernel
5.10.112-11or later
Run uname -r to check the kernel version on your instance.
How it works
Hugetext works similarly to THP but targets only code segments rather than all anonymous memory. When enabled, the kernel asynchronously scans executable memory mappings—binary files and DLLs—and consolidates qualifying pages into 2 MB huge pages. This reduces the number of iTLB entries required, lowering the iTLB miss rate and improving CPU efficiency throughout the lifetime of the application.
Because Hugetext operates asynchronously, pages are not merged immediately when you enable the feature, and they are not split immediately when you disable it.
Enable Hugetext
Hugetext is disabled by default. Enable it through the sysfs interface by writing one of the following values to /sys/kernel/mm/transparent_hugepage/hugetext_enabled.
| Value | Mode | Description |
|---|---|---|
1 | Binary pages and dynamic library pages | Maps executable sections of binary files and DLLs to huge pages. Use this for most database and application workloads. |
2 | Anonymous executable pages | Maps anonymous executable pages (JIT-compiled code) to huge pages. Use this for Java or other JIT-based runtimes. |
3 | All of the above | Combines modes 1 and 2. Use this when your workload includes both static binaries and JIT-compiled code. |
Run the corresponding command:
Mode 1 — Binary pages and dynamic library pages:
sudo sh -c 'echo 1 > /sys/kernel/mm/transparent_hugepage/hugetext_enabled'Mode 2 — Anonymous executable pages:
sudo sh -c 'echo 2 > /sys/kernel/mm/transparent_hugepage/hugetext_enabled'Mode 3 — Binary pages, dynamic library pages, and anonymous executable pages:
sudo sh -c 'echo 3 > /sys/kernel/mm/transparent_hugepage/hugetext_enabled'
Configure Hugetext at boot
To make the Hugetext setting persist across reboots, set the hugetext boot parameter in your GRand Unified Bootloader (GRUB) configuration. The parameter accepts the same values (0, 1, 2, or 3) as described in the table above. Refer to your GRUB version and image documentation for the exact syntax.
Verify that Hugetext is active
After enabling Hugetext, allow time for the kernel to consolidate pages asynchronously. Then check the FilePmdMapped field in /proc/<pid>/smaps, which reports the size of huge pages mapped to a process (in KB).
Replace <pid> with the actual process ID. To find the process ID for a running service, use pidof. For example: pidof sshd.
sudo cat /proc/<pid>/smaps | grep FilePmdMapped | awk '{sum+=$2}END{print"Sum= ",sum}'A Sum value greater than 0 confirms that the process is using huge pages. If the value is 0, the kernel has not yet consolidated pages for that process, or the process does not have qualifying code segments.
Disable Hugetext
sudo sh -c 'echo 0 > /sys/kernel/mm/transparent_hugepage/hugetext_enabled'After disabling, the kernel does not immediately split existing huge pages. Huge page caches also persist. To clear them, use one of the following methods.
Clear huge page caches
Run one of these commands before benchmarking to make sure test results are not skewed by cached huge pages from a previous session.
Clear the system-wide page cache:
sudo sh -c 'echo 3 > /proc/sys/vm/drop_caches'Clear the page cache for a specific file:
sudo vmtouch -e /<path>/targetReplace
<path>with the directory of your application binary. Virtual Memory Toucher (vmtouch) must be installed. If it is not, run:sudo yum install vmtouchSplit residual huge pages:
sudo sh -c 'echo 1 > /sys/kernel/debug/split_huge_pages'
Enable padding
Padding is an optional optimization for cases where a binary's text segment is smaller than 2 MB and therefore cannot use a huge page on its own. When the text segment size exceeds the value of hugetext_pad_threshold, the kernel pads the segment to 2 MB, allowing it to be mapped to a huge page.
Padding requires Hugetext to be enabled.
Enable padding by setting hugetext_pad_threshold (valid range: 0–2097151):
sudo sh -c 'echo [0~2097151] > /sys/kernel/mm/transparent_hugepage/hugetext_pad_threshold'A value of 4096 works well for most cases:
sudo sh -c 'echo 4096 > /sys/kernel/mm/transparent_hugepage/hugetext_pad_threshold'To disable padding:
sudo sh -c 'echo 0 > /sys/kernel/mm/transparent_hugepage/hugetext_pad_threshold'Alignment note: For padding to work as expected, code and data segments should be 2 MB aligned. To align them, modify the default linker script (IDS file) and add . = ALIGN(0x200000); before each code or data segment. Without 2 MB alignment, content following rw-p or r--p segments may not be padded as expected, and some sections may fall back to 4 KB pages.
Performance benefits
On physical machines, Hugetext typically improves application performance by 5%–8%. Virtual machines often see higher gains because the TLB pressure relief is more pronounced in virtualized environments.
The following results are from a MySQL benchmark on an Arm platform with a 32 virtual CPU (vCPU) instance.
Transactions per second (TPS): 2 MB huge pages vs. 4 KB standard pages
| Concurrency | Performance gain |
|---|---|
| 1 connection | ~6.9% higher TPS with huge pages |
| 8–16 connections (CPU contention eliminated, ~25%–50% utilization) | >6.5% higher TPS |
| 32 connections (CPU at 100%, competing workloads) | ~11% higher TPS; huge pages also show more stable TPS |
iTLB metrics: huge pages vs. 4 KB pages
After enabling Hugetext for MySQL:
iTLB misses dropped approximately tenfold.
iTLB miss rate fell from ~0.09% to ~0.08%.
iTLB misses per kilo-instructions (MPKI) decreased approximately sixfold.
PostgreSQL can also use huge pages to gain a 7% increase in performance.
Key concepts
| Term | Description |
|---|---|
| Huge page | A memory page larger than the standard 4 KB. Huge pages reduce the number of Translation Lookaside Buffer (TLB) entries needed and improve memory access efficiency. |
| Transparent Huge Pages (THP) | A kernel feature that asynchronously consolidates small pages into 2 MB huge pages by scanning the virtual memory area (VMA) of each process. THP targets anonymous memory. |
| Hugetext | A THP extension that consolidates only code segments into huge pages, targeting executable binary sections and DLLs. |
| iTLB miss | Occurs when the CPU finds no matching entry in the instruction TLB (iTLB). A high miss rate reduces CPU throughput. |
| iTLB utilization | The proportion of iTLB entries that are actively used. Higher utilization means fewer misses and better CPU throughput. |
| iTLB MPKI | iTLB misses per kilo-instructions. A lower value indicates better CPU efficiency. |
What's next
Alibaba Cloud Linux also supports standard THP to improve memory access efficiency for data segments. THP consolidates 4 KB pages into 2 MB or larger huge pages, reducing page table entries (PTEs) and TLB pressure across all memory types. For details, see How do I use THP to tune performance on Alibaba Cloud Linux?