The prctl(PR_FUTEX_HASH) is queued for the v6.16 merge window.
Add some documentation of the interface.
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
man/man2/prctl.2 | 3 +
man/man2const/PR_FUTEX_HASH.2const | 89 ++++++++++++++++++++++++++++++
2 files changed, 92 insertions(+)
create mode 100644 man/man2const/PR_FUTEX_HASH.2const
diff --git a/man/man2/prctl.2 b/man/man2/prctl.2
index cb5e75bf79ab2..ddfd1d1f5b940 100644
--- a/man/man2/prctl.2
+++ b/man/man2/prctl.2
@@ -150,6 +150,8 @@ with a significance depending on the first one.
.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 0000000000000..08511b18335b2
--- /dev/null
+++ b/man/man2const/PR_FUTEX_HASH.2const
@@ -0,0 +1,89 @@
+.\" 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)
--
2.49.0Hi Sebastian, On Mon, Jun 02, 2025 at 04:01:01PM +0200, Sebastian Andrzej Siewior wrote: > The prctl(PR_FUTEX_HASH) is queued for the v6.16 merge window. > Add some documentation of the interface. > > Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de> LGTM, thanks! Please let me know when this is merged into Linus's tree. Have a lovely day! Alex > --- > man/man2/prctl.2 | 3 + > man/man2const/PR_FUTEX_HASH.2const | 89 ++++++++++++++++++++++++++++++ > 2 files changed, 92 insertions(+) > create mode 100644 man/man2const/PR_FUTEX_HASH.2const > > diff --git a/man/man2/prctl.2 b/man/man2/prctl.2 > index cb5e75bf79ab2..ddfd1d1f5b940 100644 > --- a/man/man2/prctl.2 > +++ b/man/man2/prctl.2 > @@ -150,6 +150,8 @@ with a significance depending on the first one. > .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 0000000000000..08511b18335b2 > --- /dev/null > +++ b/man/man2const/PR_FUTEX_HASH.2const > @@ -0,0 +1,89 @@ > +.\" 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) > -- > 2.49.0 > > -- <https://www.alejandro-colomar.es/>
On 2025-06-11 10:43:07 [+0200], Alejandro Colomar wrote: > Hi Sebastian, Hi, > On Mon, Jun 02, 2025 at 04:01:01PM +0200, Sebastian Andrzej Siewior wrote: > > The prctl(PR_FUTEX_HASH) is queued for the v6.16 merge window. > > Add some documentation of the interface. > > > > Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de> > > LGTM, thanks! Please let me know when this is merged into Linus's tree. This is in v6.16-rc1 since last Monday. We do regression handling now but I think it will stay. I can poke you once v6.16 is out in case we need a last minute revert of this. > Have a lovely day! > Alex Sebastian
Hi Sebastian, On Wed, Jun 11, 2025 at 10:47:16AM +0200, Sebastian Andrzej Siewior wrote: > On 2025-06-11 10:43:07 [+0200], Alejandro Colomar wrote: > > Hi Sebastian, > Hi, > > > On Mon, Jun 02, 2025 at 04:01:01PM +0200, Sebastian Andrzej Siewior wrote: > > > The prctl(PR_FUTEX_HASH) is queued for the v6.16 merge window. > > > Add some documentation of the interface. > > > > > > Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de> > > > > LGTM, thanks! Please let me know when this is merged into Linus's tree. > > This is in v6.16-rc1 since last Monday. We do regression handling now > but I think it will stay. I can poke you once v6.16 is out in case we > need a last minute revert of this. Thanks! I've applied patch 1/4, with the following amendments: diff --git i/man/man2const/PR_FUTEX_HASH.2const w/man/man2const/PR_FUTEX_HASH.2const index 08511b183..b500c943b 100644 --- i/man/man2const/PR_FUTEX_HASH.2const +++ w/man/man2const/PR_FUTEX_HASH.2const @@ -53,14 +53,16 @@ .SH DESCRIPTION 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 +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. +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. +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 <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=243de1dbc9cf818fa71c97856cbaf88b9d255b44> Cheers, Alex -- <https://www.alejandro-colomar.es/>
© 2016 - 2025 Red Hat, Inc.