1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
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)
|
