Debian Codegraph @

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

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
4 .\" may be freely modified and distributed
5 .\" %%%LICENSE_END
6 .\"
7 .TH FUTEX_CMP_REQUEUE 2const 2025-09-21 "Linux man-pages 6.18"
8 .SH NAME
9 FUTEX_CMP_REQUEUE \- compare a futex, wake some waiters, and requeue others
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
16 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
17 .B #include <unistd.h>
18 .P
19 .BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_CMP_REQUEUE,"
20 .BI " uint32_t " val ", uint32_t " val2 ", uint32_t *" uaddr2 ,
21 .BI " uint32_t " val3 );
22 .fi
23 .SH DESCRIPTION
24 This operation first checks whether the location
25 .I uaddr
26 still contains the value
27 .IR val3 .
28 If not, the operation fails with the error
29 .BR EAGAIN .
30 Otherwise, the operation wakes up a maximum of
31 .I val
32 waiters that are waiting on the futex at
33 .IR uaddr .
34 If there are more than
35 .I val
36 waiters, then the remaining waiters are removed
37 from the wait queue of the source futex at
38 .I uaddr
39 and added to the wait queue of the target futex at
40 .IR uaddr2 .
41 The
42 .I val2
43 argument specifies an upper limit on the number of waiters
44 that are requeued to the futex at
45 .IR uaddr2 .
46 .P
47 .\" FIXME(Torvald) Is the following correct? Or is just the decision
48 .\" which threads to wake or requeue part of the atomic operation?
49 The load from
50 .I uaddr
51 is an atomic memory access (i.e., using atomic machine instructions of
52 the respective architecture).
53 This load, the comparison with
54 .IR val3 ,
55 and the requeueing of any waiters are performed atomically and totally
56 ordered with respect to other operations on the same futex word.
57 .\" Notes from a f2f conversation with Thomas Gleixner (Aug 2015): ###
58 .\" The operation is serialized with respect to operations on both
59 .\" source and target futex. No other waiter can enqueue itself
60 .\" for waiting and no other waiter can dequeue itself because of
61 .\" a timeout or signal.
62 .P
63 Typical values to specify for
64 .I val
65 are 0 or 1.
66 (Specifying
67 .I val
68 as
69 .B INT_MAX
70 is not useful,
71 because it would make the
72 .B FUTEX_CMP_REQUEUE
73 operation equivalent to
74 .BR FUTEX_WAKE (2const).)
75 The limit value specified via
76 .I val2
77 is typically either 1 or
78 .BR INT_MAX .
79 (Specifying
80 .I val2
81 as 0 is not useful,
82 because it would make the
83 .B FUTEX_CMP_REQUEUE
84 operation equivalent to
85 .BR FUTEX_WAKE (2const).)
86 .P
87 The
88 .B FUTEX_CMP_REQUEUE
89 operation was added as a replacement for the earlier
90 .BR FUTEX_REQUEUE (2const).
91 The difference is that the check of the value at
92 .I uaddr
93 can be used to ensure that requeueing happens only under certain
94 conditions, which allows race conditions to be avoided in certain use cases.
95 .\" But, as Rich Felker points out, there remain valid use cases for
96 .\" FUTEX_REQUEUE, for example, when the calling thread is requeuing
97 .\" the target(s) to a lock that the calling thread owns
98 .\" From: Rich Felker <[email protected]>
99 .\" Date: Wed, 29 Oct 2014 22:43:17 -0400
100 .\" To: Darren Hart <[email protected]>
101 .\" CC: [email protected], ...
102 .\" Subject: Re: Add futex wrapper to glibc?
103 .P
104 Both
105 .BR FUTEX_REQUEUE (2const)
106 and
107 .B FUTEX_CMP_REQUEUE
108 can be used to avoid "thundering herd" wake-ups that could occur when using
109 .BR FUTEX_WAKE (2const)
110 in cases where all of the waiters that are woken need to acquire
111 another futex.
112 Consider the following scenario,
113 where multiple waiter threads are waiting on B,
114 a wait queue implemented using a futex:
115 .P
116 .in +4n
117 .EX
118 lock(A)
119 while (!check_value(V)) {
120 unlock(A);
121 block_on(B);
122 lock(A);
123 };
124 unlock(A);
125 .EE
126 .in
127 .P
128 If a waker thread used
129 .BR FUTEX_WAKE (2const),
130 then all waiters waiting on B would be woken up,
131 and they would all try to acquire lock A.
132 However, waking all of the threads in this manner would be pointless because
133 all except one of the threads would immediately block on lock A again.
134 By contrast, a requeue operation wakes just one waiter and moves
135 the other waiters to lock A,
136 and when the woken waiter unlocks A then the next waiter can proceed.
137 .\"
138 .SH RETURN VALUE
139 On error,
140 \-1 is returned,
141 and
142 .I errno
143 is set to indicate the error.
144 .P
145 On success,
146 .B FUTEX_CMP_REQUEUE
147 returns the total number of waiters that were woken up or
148 requeued to the futex for the futex word at
149 .IR uaddr2 .
150 If this value is greater than
151 .IR val ,
152 then the difference is the number of waiters requeued to the futex for the
153 futex word at
154 .IR uaddr2 .
155 .SH ERRORS
156 See
157 .BR futex (2).
158 .TP
159 .B EAGAIN
160 The value pointed to by
161 .I uaddr
162 is not equal to the expected value
163 .IR val3 .
164 .TP
165 .B EFAULT
166 .I uaddr2
167 did not point to a valid user-space address.
168 .TP
169 .B EINVAL
170 .I uaddr2
171 does not point to a valid object\[em]that is,
172 the address is not four-byte-aligned.
173 .TP
174 .B EINVAL
175 The kernel detected an inconsistency between the user-space state at
176 .I uaddr
177 and the kernel state\[em]that is, it detected a waiter which waits in
178 .BR FUTEX_LOCK_PI (2const)
179 or
180 .BR FUTEX_LOCK_PI2 (2const)
181 on
182 .IR uaddr .
183 .SH STANDARDS
184 Linux.
185 .SH HISTORY
186 Linux 2.6.7.
187 .SH SEE ALSO
188 .BR futex (2)