Debian Codegraph @

upstream/debian-unstable/man2/PR_FUTEX_HASH.2const

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH PR_FUTEX_HASH 2const 2025-08-19 "Linux man-pages 6.18"
6 .SH NAME
7 PR_FUTEX_HASH
8 \-
9 configure the private futex hash
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <linux/prctl.h>" " /* Definition of " PR_* " constants */"
16 .B #include <sys/prctl.h>
17 .P
18 .BI "int prctl(PR_FUTEX_HASH, unsigned long " op ", ...);"
19 .fi
20 .SH DESCRIPTION
21 Configure the attributes for the underlying hash used by the
22 .BR futex (2)
23 family of operations.
24 The Linux kernel uses a hash to distribute the unrelated
25 .BR futex (2)
26 requests to different data structures
27 in order to reduce the lock contention.
28 Unrelated requests are requests which are not related to one another
29 because they use a different futex word.
30 The data structure holds the in-kernel representation of the operation and
31 keeps track of the current users which are enqueued and wait for a wake up.
32 It also provides synchronisation of waiters against wakers.
33 The size of the global hash is determined at boot time
34 and is based on the number of CPUs in the system.
35 Due to hash collision,
36 two unrelated
37 .BR futex (2)
38 requests can share the same hash bucket.
39 This in turn can lead to delays of the
40 .BR futex (2)
41 operation due to lock contention while accessing the data structure.
42 These delays can be problematic on a real-time system
43 since random processes can
44 share in-kernel locks
45 and it is not deterministic which process will be involved.
46 .P
47 Linux 6.17 implements a process-wide private hash which is used by all
48 .BR futex (2)
49 operations that specify the
50 .B FUTEX_PRIVATE_FLAG
51 option as part of the operation.
52 Without any configuration
53 the kernel will allocate 16 hash slots
54 once the first thread has been created.
55 If the process continues to create threads,
56 the kernel will try to resize the private hash
57 based on the number of threads
58 and available CPUs in the system.
59 The kernel will only increase the size
60 and will make sure
61 it does not exceed the size of the global hash.
62 .P
63 The user can configure the size of the private hash
64 which will also
65 disable the automatic resize provided by the kernel.
66 .P
67 The value in
68 .I op
69 is one of the options below.
70 .TP
71 .B PR_FUTEX_HASH_GET_SLOTS
72 .TQ
73 .B PR_FUTEX_HASH_SET_SLOTS
74 .SH RETURN VALUE
75 On success,
76 these calls return a nonnegative value.
77 On error, \-1 is returned, and
78 .I errno
79 is set to indicate the error.
80 .SH STANDARDS
81 Linux.
82 .SH HISTORY
83 Linux 6.17.
84 .SH SEE ALSO
85 .BR prctl (2),
86 .BR futex (2),
87 .BR PR_FUTEX_HASH_GET_SLOTS (2const),
88 .BR PR_FUTEX_HASH_SET_SLOTS (2const)