diff options
| author | Sebastian Andrzej Siewior <bigeasy@linutronix.de> | 2025-06-02 16:01:01 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2025-06-11 13:56:52 +0200 |
| commit | e00ed36b54405ee36b3b26839a228c802da3e361 (patch) | |
| tree | f49a5538f985addf84fe7c9e6611a353a0fc0041 | |
| parent | d1324c82d0fedb45678d7c74cda2200f14f75a72 (diff) | |
| download | man-pages-e00ed36b54405ee36b3b26839a228c802da3e361.tar.gz | |
man/man2/prctl.2, man/man2const/PR_FUTEX_HASH.2const: Document PR_FUTEX_HASH
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Message-ID: <20250602140104.2769223-2-bigeasy@linutronix.de>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
| -rw-r--r-- | man/man2/prctl.2 | 3 | ||||
| -rw-r--r-- | man/man2const/PR_FUTEX_HASH.2const | 91 |
2 files changed, 94 insertions, 0 deletions
diff --git a/man/man2/prctl.2 b/man/man2/prctl.2 index cb5e75bf79..ddfd1d1f5b 100644 --- a/man/man2/prctl.2 +++ b/man/man2/prctl.2 @@ -150,6 +150,8 @@ The first argument can be: .B PR_GET_MDWE .TQ .B PR_RISCV_SET_ICACHE_FLUSH_CTX +.TQ +.B PR_FUTEX_HASH .SH RETURN VALUE On success, a nonnegative value is returned. @@ -262,4 +264,5 @@ so these operations should be used with care. .BR PR_SET_MDWE (2const), .BR PR_GET_MDWE (2const), .BR PR_RISCV_SET_ICACHE_FLUSH_CTX (2const), +.BR PR_FUTEX_HASH (2const), .BR core (5) diff --git a/man/man2const/PR_FUTEX_HASH.2const b/man/man2const/PR_FUTEX_HASH.2const new file mode 100644 index 0000000000..b500c943bf --- /dev/null +++ b/man/man2const/PR_FUTEX_HASH.2const @@ -0,0 +1,91 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH PR_FUTEX_HASH 2const (date) "Linux man-pages (unreleased)" +.SH NAME +PR_FUTEX_HASH +\- +configure the private futex hash +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <linux/prctl.h>" " /* Definition of " PR_* " constants */" +.B #include <sys/prctl.h> +.P +.BI "int prctl(PR_FUTEX_HASH, unsigned long " op ", ...);" +.fi +.SH DESCRIPTION +Configure the attributes for the underlying hash used by the +.BR futex (2) +family of operations. +The Linux kernel uses a hash to distribute the unrelated +.BR futex (2) +requests to different data structures +in order to reduce the lock contention. +Unrelated requests are requests which are not related to one another +because they use a different futex word. +The data structure holds the in-kernel representation of the operation and +keeps track of the current users which are enqueued and wait for a wake up. +It also provides synchronisation of waiters against wakers. +The size of the global hash is determined at boot time +and is based on the number of CPUs in the system. +Due to hash collision, +two unrelated +.BR futex (2) +requests can share the same hash bucket. +This in turn can lead to delays of the +.BR futex (2) +operation due to lock contention while accessing the data structure. +These delays can be problematic on a real-time system +since random processes can +share in-kernel locks +and it is not deterministic which process will be involved. +.P +Linux 6.16 implements a process-wide private hash which is used by all +.BR futex (2) +operations that specify the +.B FUTEX_PRIVATE_FLAG +option as part of the operation. +Without any configuration +the kernel will allocate 16 hash slots +once the first thread has been created. +If the process continues to create threads, +the kernel will try to resize the private hash +based on the number of threads +and available CPUs in the system. +The kernel will only increase the size +and will make sure +it does not exceed the size of the global hash. +.P +The user can configure the size of the private hash +which will also +disable the automatic resize provided by the kernel. +.P +The value in +.I op +is one of the options below. +.TP +.B PR_FUTEX_HASH_GET_IMMUTABLE +.TQ +.B PR_FUTEX_HASH_GET_SLOTS +.TQ +.B PR_FUTEX_HASH_SET_SLOTS +.SH RETURN VALUE +On success, +these calls return a nonnegative value. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 6.16. +.SH SEE ALSO +.BR prctl (2), +.BR futex (2), +.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const), +.BR PR_FUTEX_HASH_GET_SLOTS (2const), +.BR PR_FUTEX_HASH_SET_SLOTS (2const) |