PR_FUTEX_HASH(2const)

✨ PR_FUTEX_HASH ✨

okay bestie, welcome to the glow-up of PR_FUTEX_HASH(2const) 💅 it lives in the Linux man-pages, section 2const, and it's literally all about tuning the private futex hash. yes, that futex. slay.

🌸 LIBRARY

Standard C library (libc, -lc) 🫶

🎀 SYNOPSIS

#include <linux/prctl.h>  /* Definition of PR_* constants */
#include <sys/prctl.h>

int prctl(PR_FUTEX_HASH, unsigned long op, ...);

💖 DESCRIPTION

okay so. this one configures the attributes for the underlying hash that the futex(2) family of operations uses. the Linux kernel uses a hash to spread out unrelated futex(2) requests across different data structures so it can cut down the lock contention. and when I say unrelated, I mean requests that aren't related to each other because they use a different futex word. iykyk.

that data structure holds the in-kernel representation of the operation, keeps track of the current users that are enqueued and waiting for a wake up, and also synchronises the waiters against the wakers. multi-tasking icon behavior ✨

the size of the global hash is decided at boot time and is based on the number of CPUs in the system. and here's the catch, bestie: because hash collisions are a thing, two unrelated futex(2) requests can end up sharing the same hash bucket 😭 which can lead to delays in the futex(2) operation from lock contention while they're accessing that data structure. and those delays are genuinely problematic on a real-time system, because random processes can share in-kernel locks and it's not deterministic which process will be involved. not the vibe.

Linux 6.17 implements a process-wide private hash that's used by all futex(2) operations that specify the FUTEX_PRIVATE_FLAG option as part of the operation. with zero configuration, the kernel allocates 16 hash slots once the first thread has been created. and if the process keeps creating threads, the kernel will try to resize the private hash based on the number of threads and the available CPUs in the system. the kernel will only increase the size, and it makes sure it doesn't exceed the size of the global hash. no shrinking, we only grow 🌱

you, the user, can configure the size of the private hash — and doing that also disables the automatic resize that the kernel provides. so, like, once you set it, that's the set. periodt.

the value in op is one of the options below 👇

💅 Options

• PR_FUTEX_HASH_GET_SLOTS
• PR_FUTEX_HASH_SET_SLOTS

⭐ RETURN VALUE

on success, these calls return a nonnegative value 🫶 on error, -1 is returned, and errno is set to indicate the error. classic.

🌈 STANDARDS

Linux. 💀

👑 HISTORY

Linux 6.17. fresh off the press.

🦋 SEE ALSO

prctl(2), futex(2), PR_FUTEX_HASH_GET_SLOTS(2const), PR_FUTEX_HASH_SET_SLOTS(2const)

---

okay that's the whole page, babe, you ate it 💖 this was Linux man-pages 6.20, dated 2025-08-19, and it was the PR_FUTEX_HASH(2const) page. go forth and configure ur hash, main character 💅✨