1futex(2) System Calls Manual futex(2)
2
6 futex - fast user-space locking
7
9 Standard C library (libc, -lc)
10
12 #include <linux/futex.h> /* Definition of FUTEX_* constants */
13 #include <sys/syscall.h> /* Definition of SYS_* constants */
14 #include <unistd.h>
15 long syscall(SYS_futex, uint32_t *uaddr, int futex_op, uint32_t val,
17 const struct timespec *timeout, /* or: uint32_t val2 */
18 uint32_t *uaddr2, uint32_t val3);
19 Note: glibc provides no wrapper for futex(), necessitating the use of
21 syscall(2).
22
24 The futex() system call provides a method for waiting until a certain
25 condition becomes true. It is typically used as a blocking construct
26 in the context of shared-memory synchronization. When using futexes,
27 the majority of the synchronization operations are performed in user
28 space. A user-space program employs the futex() system call only when
29 it is likely that the program has to block for a longer time until the
30 condition becomes true. Other futex() operations can be used to wake
31 any processes or threads waiting for a particular condition.
32 A futex is a 32-bit value—referred to below as a futex word—whose ad‐
34 dress is supplied to the futex() system call. (Futexes are 32 bits in
35 size on all platforms, including 64-bit systems.) All futex operations
36 are governed by this value. In order to share a futex between pro‐
37 cesses, the futex is placed in a region of shared memory, created using
38 (for example) mmap(2) or shmat(2). (Thus, the futex word may have dif‐
39 ferent virtual addresses in different processes, but these addresses
40 all refer to the same location in physical memory.) In a multithreaded
41 program, it is sufficient to place the futex word in a global variable
42 shared by all threads.
43 When executing a futex operation that requests to block a thread, the
45 kernel will block only if the futex word has the value that the calling
46 thread supplied (as one of the arguments of the futex() call) as the
47 expected value of the futex word. The loading of the futex word's
48 value, the comparison of that value with the expected value, and the
49 actual blocking will happen atomically and will be totally ordered with
50 respect to concurrent operations performed by other threads on the same
51 futex word. Thus, the futex word is used to connect the synchroniza‐
52 tion in user space with the implementation of blocking by the kernel.
53 Analogously to an atomic compare-and-exchange operation that poten‐
54 tially changes shared memory, blocking via a futex is an atomic com‐
55 pare-and-block operation.
56 One use of futexes is for implementing locks. The state of the lock
58 (i.e., acquired or not acquired) can be represented as an atomically
59 accessed flag in shared memory. In the uncontended case, a thread can
60 access or modify the lock state with atomic instructions, for example
61 atomically changing it from not acquired to acquired using an atomic
62 compare-and-exchange instruction. (Such instructions are performed en‐
63 tirely in user mode, and the kernel maintains no information about the
64 lock state.) On the other hand, a thread may be unable to acquire a
65 lock because it is already acquired by another thread. It then may
66 pass the lock's flag as a futex word and the value representing the ac‐
67 quired state as the expected value to a futex() wait operation. This
68 futex() operation will block if and only if the lock is still acquired
69 (i.e., the value in the futex word still matches the "acquired state").
70 When releasing the lock, a thread has to first reset the lock state to
71 not acquired and then execute a futex operation that wakes threads
72 blocked on the lock flag used as a futex word (this can be further op‐
73 timized to avoid unnecessary wake-ups). See futex(7) for more detail
74 on how to use futexes.
75 Besides the basic wait and wake-up futex functionality, there are fur‐
77 ther futex operations aimed at supporting more complex use cases.
78 Note that no explicit initialization or destruction is necessary to use
80 futexes; the kernel maintains a futex (i.e., the kernel-internal imple‐
81 mentation artifact) only while operations such as FUTEX_WAIT, described
82 below, are being performed on a particular futex word.
83 Arguments
85 The uaddr argument points to the futex word. On all platforms, futexes
86 are four-byte integers that must be aligned on a four-byte boundary.
87 The operation to perform on the futex is specified in the futex_op ar‐
88 gument; val is a value whose meaning and purpose depends on futex_op.
89 The remaining arguments (timeout, uaddr2, and val3) are required only
91 for certain of the futex operations described below. Where one of
92 these arguments is not required, it is ignored.
93 For several blocking operations, the timeout argument is a pointer to a
95 timespec structure that specifies a timeout for the operation. How‐
96 ever, notwithstanding the prototype shown above, for some operations,
97 the least significant four bytes of this argument are instead used as
98 an integer whose meaning is determined by the operation. For these op‐
99 erations, the kernel casts the timeout value first to unsigned long,
100 then to uint32_t, and in the remainder of this page, this argument is
101 referred to as val2 when interpreted in this fashion.
102 Where it is required, the uaddr2 argument is a pointer to a second fu‐
104 tex word that is employed by the operation.
105 The interpretation of the final integer argument, val3, depends on the
107 operation.
108 Futex operations
110 The futex_op argument consists of two parts: a command that specifies
111 the operation to be performed, bitwise ORed with zero or more options
112 that modify the behaviour of the operation. The options that may be
113 included in futex_op are as follows:
114 FUTEX_PRIVATE_FLAG (since Linux 2.6.22)
116 This option bit can be employed with all futex operations. It
117 tells the kernel that the futex is process-private and not
118 shared with another process (i.e., it is being used for synchro‐
119 nization only between threads of the same process). This allows
120 the kernel to make some additional performance optimizations.
121 As a convenience, <linux/futex.h> defines a set of constants
123 with the suffix _PRIVATE that are equivalents of all of the op‐
124 erations listed below, but with the FUTEX_PRIVATE_FLAG ORed into
125 the constant value. Thus, there are FUTEX_WAIT_PRIVATE, FU‐
126 TEX_WAKE_PRIVATE, and so on.
127 FUTEX_CLOCK_REALTIME (since Linux 2.6.28)
129 This option bit can be employed only with the FUTEX_WAIT_BITSET,
130 FUTEX_WAIT_REQUEUE_PI, (since Linux 4.5) FUTEX_WAIT, and (since
131 Linux 5.14) FUTEX_LOCK_PI2 operations.
132 If this option is set, the kernel measures the timeout against
134 the CLOCK_REALTIME clock.
135 If this option is not set, the kernel measures the timeout
137 against the CLOCK_MONOTONIC clock.
138 The operation specified in futex_op is one of the following:
140 FUTEX_WAIT (since Linux 2.6.0)
142 This operation tests that the value at the futex word pointed to
143 by the address uaddr still contains the expected value val, and
144 if so, then sleeps waiting for a FUTEX_WAKE operation on the fu‐
145 tex word. The load of the value of the futex word is an atomic
146 memory access (i.e., using atomic machine instructions of the
147 respective architecture). This load, the comparison with the
148 expected value, and starting to sleep are performed atomically
149 and totally ordered with respect to other futex operations on
150 the same futex word. If the thread starts to sleep, it is con‐
151 sidered a waiter on this futex word. If the futex value does
152 not match val, then the call fails immediately with the error
153 EAGAIN.
154 The purpose of the comparison with the expected value is to pre‐
156 vent lost wake-ups. If another thread changed the value of the
157 futex word after the calling thread decided to block based on
158 the prior value, and if the other thread executed a FUTEX_WAKE
159 operation (or similar wake-up) after the value change and before
160 this FUTEX_WAIT operation, then the calling thread will observe
161 the value change and will not start to sleep.
162 If the timeout is not NULL, the structure it points to specifies
164 a timeout for the wait. (This interval will be rounded up to
165 the system clock granularity, and is guaranteed not to expire
166 early.) The timeout is by default measured according to the
167 CLOCK_MONOTONIC clock, but, since Linux 4.5, the CLOCK_REALTIME
168 clock can be selected by specifying FUTEX_CLOCK_REALTIME in fu‐
169 tex_op. If timeout is NULL, the call blocks indefinitely.
170 Note: for FUTEX_WAIT, timeout is interpreted as a relative
172 value. This differs from other futex operations, where timeout
173 is interpreted as an absolute value. To obtain the equivalent
174 of FUTEX_WAIT with an absolute timeout, employ FUTEX_WAIT_BITSET
175 with val3 specified as FUTEX_BITSET_MATCH_ANY.
176 The arguments uaddr2 and val3 are ignored.
178 FUTEX_WAKE (since Linux 2.6.0)
180 This operation wakes at most val of the waiters that are waiting
181 (e.g., inside FUTEX_WAIT) on the futex word at the address
182 uaddr. Most commonly, val is specified as either 1 (wake up a
183 single waiter) or INT_MAX (wake up all waiters). No guarantee
184 is provided about which waiters are awoken (e.g., a waiter with
185 a higher scheduling priority is not guaranteed to be awoken in
186 preference to a waiter with a lower priority).
187 The arguments timeout, uaddr2, and val3 are ignored.
189 FUTEX_FD (from Linux 2.6.0 up to and including Linux 2.6.25)
191 This operation creates a file descriptor that is associated with
192 the futex at uaddr. The caller must close the returned file de‐
193 scriptor after use. When another process or thread performs a
194 FUTEX_WAKE on the futex word, the file descriptor indicates as
195 being readable with select(2), poll(2), and epoll(7)
196 The file descriptor can be used to obtain asynchronous notifica‐
198 tions: if val is nonzero, then, when another process or thread
199 executes a FUTEX_WAKE, the caller will receive the signal number
200 that was passed in val.
201 The arguments timeout, uaddr2, and val3 are ignored.
203 Because it was inherently racy, FUTEX_FD has been removed from
205 Linux 2.6.26 onward.
206 FUTEX_REQUEUE (since Linux 2.6.0)
208 This operation performs the same task as FUTEX_CMP_REQUEUE (see
209 below), except that no check is made using the value in val3.
210 (The argument val3 is ignored.)
211 FUTEX_CMP_REQUEUE (since Linux 2.6.7)
213 This operation first checks whether the location uaddr still
214 contains the value val3. If not, the operation fails with the
215 error EAGAIN. Otherwise, the operation wakes up a maximum of
216 val waiters that are waiting on the futex at uaddr. If there
217 are more than val waiters, then the remaining waiters are re‐
218 moved from the wait queue of the source futex at uaddr and added
219 to the wait queue of the target futex at uaddr2. The val2 argu‐
220 ment specifies an upper limit on the number of waiters that are
221 requeued to the futex at uaddr2.
222 The load from uaddr is an atomic memory access (i.e., using
224 atomic machine instructions of the respective architecture).
225 This load, the comparison with val3, and the requeueing of any
226 waiters are performed atomically and totally ordered with re‐
227 spect to other operations on the same futex word.
228 Typical values to specify for val are 0 or 1. (Specifying
230 INT_MAX is not useful, because it would make the FUTEX_CMP_RE‐
231 QUEUE operation equivalent to FUTEX_WAKE.) The limit value
232 specified via val2 is typically either 1 or INT_MAX. (Specify‐
233 ing the argument as 0 is not useful, because it would make the
234 FUTEX_CMP_REQUEUE operation equivalent to FUTEX_WAIT.)
235 The FUTEX_CMP_REQUEUE operation was added as a replacement for
237 the earlier FUTEX_REQUEUE. The difference is that the check of
238 the value at uaddr can be used to ensure that requeueing happens
239 only under certain conditions, which allows race conditions to
240 be avoided in certain use cases.
241 Both FUTEX_REQUEUE and FUTEX_CMP_REQUEUE can be used to avoid
243 "thundering herd" wake-ups that could occur when using FU‐
244 TEX_WAKE in cases where all of the waiters that are woken need
245 to acquire another futex. Consider the following scenario,
246 where multiple waiter threads are waiting on B, a wait queue im‐
247 plemented using a futex:
248 lock(A)
250 while (!check_value(V)) {
251 unlock(A);
252 block_on(B);
253 lock(A);
254 };
255 unlock(A);
256 If a waker thread used FUTEX_WAKE, then all waiters waiting on B
258 would be woken up, and they would all try to acquire lock A.
259 However, waking all of the threads in this manner would be
260 pointless because all except one of the threads would immedi‐
261 ately block on lock A again. By contrast, a requeue operation
262 wakes just one waiter and moves the other waiters to lock A, and
263 when the woken waiter unlocks A then the next waiter can pro‐
264 ceed.
265 FUTEX_WAKE_OP (since Linux 2.6.14)
267 This operation was added to support some user-space use cases
268 where more than one futex must be handled at the same time. The
269 most notable example is the implementation of pthread_cond_sig‐
270 nal(3), which requires operations on two futexes, the one used
271 to implement the mutex and the one used in the implementation of
272 the wait queue associated with the condition variable. FU‐
273 TEX_WAKE_OP allows such cases to be implemented without leading
274 to high rates of contention and context switching.
275 The FUTEX_WAKE_OP operation is equivalent to executing the fol‐
277 lowing code atomically and totally ordered with respect to other
278 futex operations on any of the two supplied futex words:
279 uint32_t oldval = *(uint32_t *) uaddr2;
281 *(uint32_t *) uaddr2 = oldval op oparg;
282 futex(uaddr, FUTEX_WAKE, val, 0, 0, 0);
283 if (oldval cmp cmparg)
284 futex(uaddr2, FUTEX_WAKE, val2, 0, 0, 0);
285 In other words, FUTEX_WAKE_OP does the following:
287 • saves the original value of the futex word at uaddr2 and per‐
289 forms an operation to modify the value of the futex at
290 uaddr2; this is an atomic read-modify-write memory access
291 (i.e., using atomic machine instructions of the respective
292 architecture)
293 • wakes up a maximum of val waiters on the futex for the futex
295 word at uaddr; and
296 • dependent on the results of a test of the original value of
298 the futex word at uaddr2, wakes up a maximum of val2 waiters
299 on the futex for the futex word at uaddr2.
300 The operation and comparison that are to be performed are en‐
302 coded in the bits of the argument val3. Pictorially, the encod‐
303 ing is:
304 +---+---+-----------+-----------+
306 |op |cmp| oparg | cmparg |
307 +---+---+-----------+-----------+
308 4 4 12 12 <== # of bits
309 Expressed in code, the encoding is:
311 #define FUTEX_OP(op, oparg, cmp, cmparg) \
313 (((op & 0xf) << 28) | \
314 ((cmp & 0xf) << 24) | \
315 ((oparg & 0xfff) << 12) | \
316 (cmparg & 0xfff))
317 In the above, op and cmp are each one of the codes listed below.
319 The oparg and cmparg components are literal numeric values, ex‐
320 cept as noted below.
321 The op component has one of the following values:
323 FUTEX_OP_SET 0 /* uaddr2 = oparg; */
325 FUTEX_OP_ADD 1 /* uaddr2 += oparg; */
326 FUTEX_OP_OR 2 /* uaddr2 |= oparg; */
327 FUTEX_OP_ANDN 3 /* uaddr2 &= ~oparg; */
328 FUTEX_OP_XOR 4 /* uaddr2 ^= oparg; */
329 In addition, bitwise ORing the following value into op causes
331 (1 << oparg) to be used as the operand:
332 FUTEX_OP_ARG_SHIFT 8 /* Use (1 << oparg) as operand */
334 The cmp field is one of the following:
336 FUTEX_OP_CMP_EQ 0 /* if (oldval == cmparg) wake */
338 FUTEX_OP_CMP_NE 1 /* if (oldval != cmparg) wake */
339 FUTEX_OP_CMP_LT 2 /* if (oldval < cmparg) wake */
340 FUTEX_OP_CMP_LE 3 /* if (oldval <= cmparg) wake */
341 FUTEX_OP_CMP_GT 4 /* if (oldval > cmparg) wake */
342 FUTEX_OP_CMP_GE 5 /* if (oldval >= cmparg) wake */
343 The return value of FUTEX_WAKE_OP is the sum of the number of
345 waiters woken on the futex uaddr plus the number of waiters wo‐
346 ken on the futex uaddr2.
347 FUTEX_WAIT_BITSET (since Linux 2.6.25)
349 This operation is like FUTEX_WAIT except that val3 is used to
350 provide a 32-bit bit mask to the kernel. This bit mask, in
351 which at least one bit must be set, is stored in the kernel-in‐
352 ternal state of the waiter. See the description of FU‐
353 TEX_WAKE_BITSET for further details.
354 If timeout is not NULL, the structure it points to specifies an
356 absolute timeout for the wait operation. If timeout is NULL,
357 the operation can block indefinitely.
358 The uaddr2 argument is ignored.
360 FUTEX_WAKE_BITSET (since Linux 2.6.25)
362 This operation is the same as FUTEX_WAKE except that the val3
363 argument is used to provide a 32-bit bit mask to the kernel.
364 This bit mask, in which at least one bit must be set, is used to
365 select which waiters should be woken up. The selection is done
366 by a bitwise AND of the "wake" bit mask (i.e., the value in
367 val3) and the bit mask which is stored in the kernel-internal
368 state of the waiter (the "wait" bit mask that is set using FU‐
369 TEX_WAIT_BITSET). All of the waiters for which the result of
370 the AND is nonzero are woken up; the remaining waiters are left
371 sleeping.
372 The effect of FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET is to al‐
374 low selective wake-ups among multiple waiters that are blocked
375 on the same futex. However, note that, depending on the use
376 case, employing this bit-mask multiplexing feature on a futex
377 can be less efficient than simply using multiple futexes, be‐
378 cause employing bit-mask multiplexing requires the kernel to
379 check all waiters on a futex, including those that are not in‐
380 terested in being woken up (i.e., they do not have the relevant
381 bit set in their "wait" bit mask).
382 The constant FUTEX_BITSET_MATCH_ANY, which corresponds to all 32
384 bits set in the bit mask, can be used as the val3 argument for
385 FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET. Other than differences
386 in the handling of the timeout argument, the FUTEX_WAIT opera‐
387 tion is equivalent to FUTEX_WAIT_BITSET with val3 specified as
388 FUTEX_BITSET_MATCH_ANY; that is, allow a wake-up by any waker.
389 The FUTEX_WAKE operation is equivalent to FUTEX_WAKE_BITSET with
390 val3 specified as FUTEX_BITSET_MATCH_ANY; that is, wake up any
391 waiter(s).
392 The uaddr2 and timeout arguments are ignored.
394 Priority-inheritance futexes
396 Linux supports priority-inheritance (PI) futexes in order to handle
397 priority-inversion problems that can be encountered with normal futex
398 locks. Priority inversion is the problem that occurs when a high-pri‐
399 ority task is blocked waiting to acquire a lock held by a low-priority
400 task, while tasks at an intermediate priority continuously preempt the
401 low-priority task from the CPU. Consequently, the low-priority task
402 makes no progress toward releasing the lock, and the high-priority task
403 remains blocked.
404 Priority inheritance is a mechanism for dealing with the priority-in‐
406 version problem. With this mechanism, when a high-priority task be‐
407 comes blocked by a lock held by a low-priority task, the priority of
408 the low-priority task is temporarily raised to that of the high-prior‐
409 ity task, so that it is not preempted by any intermediate level tasks,
410 and can thus make progress toward releasing the lock. To be effective,
411 priority inheritance must be transitive, meaning that if a high-prior‐
412 ity task blocks on a lock held by a lower-priority task that is itself
413 blocked by a lock held by another intermediate-priority task (and so
414 on, for chains of arbitrary length), then both of those tasks (or more
415 generally, all of the tasks in a lock chain) have their priorities
416 raised to be the same as the high-priority task.
417 From a user-space perspective, what makes a futex PI-aware is a policy
419 agreement (described below) between user space and the kernel about the
420 value of the futex word, coupled with the use of the PI-futex opera‐
421 tions described below. (Unlike the other futex operations described
422 above, the PI-futex operations are designed for the implementation of
423 very specific IPC mechanisms.)
424 The PI-futex operations described below differ from the other futex op‐
426 erations in that they impose policy on the use of the value of the fu‐
427 tex word:
428 • If the lock is not acquired, the futex word's value shall be 0.
430 • If the lock is acquired, the futex word's value shall be the thread
432 ID (TID; see gettid(2)) of the owning thread.
433 • If the lock is owned and there are threads contending for the lock,
435 then the FUTEX_WAITERS bit shall be set in the futex word's value;
436 in other words, this value is:
437 FUTEX_WAITERS | TID
439 (Note that is invalid for a PI futex word to have no owner and FU‐
441 TEX_WAITERS set.)
442 With this policy in place, a user-space application can acquire an un‐
444 acquired lock or release a lock using atomic instructions executed in
445 user mode (e.g., a compare-and-swap operation such as cmpxchg on the
446 x86 architecture). Acquiring a lock simply consists of using compare-
447 and-swap to atomically set the futex word's value to the caller's TID
448 if its previous value was 0. Releasing a lock requires using compare-
449 and-swap to set the futex word's value to 0 if the previous value was
450 the expected TID.
451 If a futex is already acquired (i.e., has a nonzero value), waiters
453 must employ the FUTEX_LOCK_PI or FUTEX_LOCK_PI2 operations to acquire
454 the lock. If other threads are waiting for the lock, then the FU‐
455 TEX_WAITERS bit is set in the futex value; in this case, the lock owner
456 must employ the FUTEX_UNLOCK_PI operation to release the lock.
457 In the cases where callers are forced into the kernel (i.e., required
459 to perform a futex() call), they then deal directly with a so-called
460 RT-mutex, a kernel locking mechanism which implements the required pri‐
461 ority-inheritance semantics. After the RT-mutex is acquired, the futex
462 value is updated accordingly, before the calling thread returns to user
463 space.
464 It is important to note that the kernel will update the futex word's
466 value prior to returning to user space. (This prevents the possibility
467 of the futex word's value ending up in an invalid state, such as having
468 an owner but the value being 0, or having waiters but not having the
469 FUTEX_WAITERS bit set.)
470 If a futex has an associated RT-mutex in the kernel (i.e., there are
472 blocked waiters) and the owner of the futex/RT-mutex dies unexpectedly,
473 then the kernel cleans up the RT-mutex and hands it over to the next
474 waiter. This in turn requires that the user-space value is updated ac‐
475 cordingly. To indicate that this is required, the kernel sets the FU‐
476 TEX_OWNER_DIED bit in the futex word along with the thread ID of the
477 new owner. User space can detect this situation via the presence of
478 the FUTEX_OWNER_DIED bit and is then responsible for cleaning up the
479 stale state left over by the dead owner.
480 PI futexes are operated on by specifying one of the values listed below
482 in futex_op. Note that the PI futex operations must be used as paired
483 operations and are subject to some additional requirements:
484 • FUTEX_LOCK_PI, FUTEX_LOCK_PI2, and FUTEX_TRYLOCK_PI pair with FU‐
486 TEX_UNLOCK_PI. FUTEX_UNLOCK_PI must be called only on a futex owned
487 by the calling thread, as defined by the value policy, otherwise the
488 error EPERM results.
489 • FUTEX_WAIT_REQUEUE_PI pairs with FUTEX_CMP_REQUEUE_PI. This must be
491 performed from a non-PI futex to a distinct PI futex (or the error
492 EINVAL results). Additionally, val (the number of waiters to be wo‐
493 ken) must be 1 (or the error EINVAL results).
494 The PI futex operations are as follows:
496 FUTEX_LOCK_PI (since Linux 2.6.18)
498 This operation is used after an attempt to acquire the lock via
499 an atomic user-mode instruction failed because the futex word
500 has a nonzero value—specifically, because it contained the (PID-
501 namespace-specific) TID of the lock owner.
502 The operation checks the value of the futex word at the address
504 uaddr. If the value is 0, then the kernel tries to atomically
505 set the futex value to the caller's TID. If the futex word's
506 value is nonzero, the kernel atomically sets the FUTEX_WAITERS
507 bit, which signals the futex owner that it cannot unlock the fu‐
508 tex in user space atomically by setting the futex value to 0.
509 After that, the kernel:
510 (1) Tries to find the thread which is associated with the owner
512 TID.
513 (2) Creates or reuses kernel state on behalf of the owner. (If
515 this is the first waiter, there is no kernel state for this
516 futex, so kernel state is created by locking the RT-mutex
517 and the futex owner is made the owner of the RT-mutex. If
518 there are existing waiters, then the existing state is
519 reused.)
520 (3) Attaches the waiter to the futex (i.e., the waiter is en‐
522 queued on the RT-mutex waiter list).
523 If more than one waiter exists, the enqueueing of the waiter is
525 in descending priority order. (For information on priority or‐
526 dering, see the discussion of the SCHED_DEADLINE, SCHED_FIFO,
527 and SCHED_RR scheduling policies in sched(7).) The owner inher‐
528 its either the waiter's CPU bandwidth (if the waiter is sched‐
529 uled under the SCHED_DEADLINE policy) or the waiter's priority
530 (if the waiter is scheduled under the SCHED_RR or SCHED_FIFO
531 policy). This inheritance follows the lock chain in the case of
532 nested locking and performs deadlock detection.
533 The timeout argument provides a timeout for the lock attempt.
535 If timeout is not NULL, the structure it points to specifies an
536 absolute timeout, measured against the CLOCK_REALTIME clock. If
537 timeout is NULL, the operation will block indefinitely.
538 The uaddr2, val, and val3 arguments are ignored.
540 FUTEX_LOCK_PI2 (since Linux 5.14)
542 This operation is the same as FUTEX_LOCK_PI, except that the
543 clock against which timeout is measured is selectable. By de‐
544 fault, the (absolute) timeout specified in timeout is measured
545 against the CLOCK_MONOTONIC clock, but if the FUTEX_CLOCK_REAL‐
546 TIME flag is specified in futex_op, then the timeout is measured
547 against the CLOCK_REALTIME clock.
548 FUTEX_TRYLOCK_PI (since Linux 2.6.18)
550 This operation tries to acquire the lock at uaddr. It is in‐
551 voked when a user-space atomic acquire did not succeed because
552 the futex word was not 0.
553 Because the kernel has access to more state information than
555 user space, acquisition of the lock might succeed if performed
556 by the kernel in cases where the futex word (i.e., the state in‐
557 formation accessible to use-space) contains stale state (FU‐
558 TEX_WAITERS and/or FUTEX_OWNER_DIED). This can happen when the
559 owner of the futex died. User space cannot handle this condi‐
560 tion in a race-free manner, but the kernel can fix this up and
561 acquire the futex.
562 The uaddr2, val, timeout, and val3 arguments are ignored.
564 FUTEX_UNLOCK_PI (since Linux 2.6.18)
566 This operation wakes the top priority waiter that is waiting in
567 FUTEX_LOCK_PI or FUTEX_LOCK_PI2 on the futex address provided by
568 the uaddr argument.
569 This is called when the user-space value at uaddr cannot be
571 changed atomically from a TID (of the owner) to 0.
572 The uaddr2, val, timeout, and val3 arguments are ignored.
574 FUTEX_CMP_REQUEUE_PI (since Linux 2.6.31)
576 This operation is a PI-aware variant of FUTEX_CMP_REQUEUE. It
577 requeues waiters that are blocked via FUTEX_WAIT_REQUEUE_PI on
578 uaddr from a non-PI source futex (uaddr) to a PI target futex
579 (uaddr2).
580 As with FUTEX_CMP_REQUEUE, this operation wakes up a maximum of
582 val waiters that are waiting on the futex at uaddr. However,
583 for FUTEX_CMP_REQUEUE_PI, val is required to be 1 (since the
584 main point is to avoid a thundering herd). The remaining wait‐
585 ers are removed from the wait queue of the source futex at uaddr
586 and added to the wait queue of the target futex at uaddr2.
587 The val2 and val3 arguments serve the same purposes as for FU‐
589 TEX_CMP_REQUEUE.
590 FUTEX_WAIT_REQUEUE_PI (since Linux 2.6.31)
592 Wait on a non-PI futex at uaddr and potentially be requeued (via
593 a FUTEX_CMP_REQUEUE_PI operation in another task) onto a PI fu‐
594 tex at uaddr2. The wait operation on uaddr is the same as for
595 FUTEX_WAIT.
596 The waiter can be removed from the wait on uaddr without re‐
598 queueing on uaddr2 via a FUTEX_WAKE operation in another task.
599 In this case, the FUTEX_WAIT_REQUEUE_PI operation fails with the
600 error EAGAIN.
601 If timeout is not NULL, the structure it points to specifies an
603 absolute timeout for the wait operation. If timeout is NULL,
604 the operation can block indefinitely.
605 The val3 argument is ignored.
607 The FUTEX_WAIT_REQUEUE_PI and FUTEX_CMP_REQUEUE_PI were added to
609 support a fairly specific use case: support for priority-inheri‐
610 tance-aware POSIX threads condition variables. The idea is that
611 these operations should always be paired, in order to ensure
612 that user space and the kernel remain in sync. Thus, in the FU‐
613 TEX_WAIT_REQUEUE_PI operation, the user-space application pre-
614 specifies the target of the requeue that takes place in the FU‐
615 TEX_CMP_REQUEUE_PI operation.
616
618 In the event of an error (and assuming that futex() was invoked via
619 syscall(2)), all operations return -1 and set errno to indicate the er‐
620 ror.
621 The return value on success depends on the operation, as described in
623 the following list:
624 FUTEX_WAIT
626 Returns 0 if the caller was woken up. Note that a wake-up can
627 also be caused by common futex usage patterns in unrelated code
628 that happened to have previously used the futex word's memory
629 location (e.g., typical futex-based implementations of Pthreads
630 mutexes can cause this under some conditions). Therefore, call‐
631 ers should always conservatively assume that a return value of 0
632 can mean a spurious wake-up, and use the futex word's value
633 (i.e., the user-space synchronization scheme) to decide whether
634 to continue to block or not.
635 FUTEX_WAKE
637 Returns the number of waiters that were woken up.
638 FUTEX_FD
640 Returns the new file descriptor associated with the futex.
641 FUTEX_REQUEUE
643 Returns the number of waiters that were woken up.
644 FUTEX_CMP_REQUEUE
646 Returns the total number of waiters that were woken up or re‐
647 queued to the futex for the futex word at uaddr2. If this value
648 is greater than val, then the difference is the number of wait‐
649 ers requeued to the futex for the futex word at uaddr2.
650 FUTEX_WAKE_OP
652 Returns the total number of waiters that were woken up. This is
653 the sum of the woken waiters on the two futexes for the futex
654 words at uaddr and uaddr2.
655 FUTEX_WAIT_BITSET
657 Returns 0 if the caller was woken up. See FUTEX_WAIT for how to
658 interpret this correctly in practice.
659 FUTEX_WAKE_BITSET
661 Returns the number of waiters that were woken up.
662 FUTEX_LOCK_PI
664 Returns 0 if the futex was successfully locked.
665 FUTEX_LOCK_PI2
667 Returns 0 if the futex was successfully locked.
668 FUTEX_TRYLOCK_PI
670 Returns 0 if the futex was successfully locked.
671 FUTEX_UNLOCK_PI
673 Returns 0 if the futex was successfully unlocked.
674 FUTEX_CMP_REQUEUE_PI
676 Returns the total number of waiters that were woken up or re‐
677 queued to the futex for the futex word at uaddr2. If this value
678 is greater than val, then difference is the number of waiters
679 requeued to the futex for the futex word at uaddr2.
680 FUTEX_WAIT_REQUEUE_PI
682 Returns 0 if the caller was successfully requeued to the futex
683 for the futex word at uaddr2.
684
686 EACCES No read access to the memory of a futex word.
687 EAGAIN (FUTEX_WAIT, FUTEX_WAIT_BITSET, FUTEX_WAIT_REQUEUE_PI) The value
689 pointed to by uaddr was not equal to the expected value val at
690 the time of the call.
691 Note: on Linux, the symbolic names EAGAIN and EWOULDBLOCK (both
693 of which appear in different parts of the kernel futex code)
694 have the same value.
695 EAGAIN (FUTEX_CMP_REQUEUE, FUTEX_CMP_REQUEUE_PI) The value pointed to
697 by uaddr is not equal to the expected value val3.
698 EAGAIN (FUTEX_LOCK_PI, FUTEX_LOCK_PI2, FUTEX_TRYLOCK_PI, FUTEX_CMP_RE‐
700 QUEUE_PI) The futex owner thread ID of uaddr (for FUTEX_CMP_RE‐
701 QUEUE_PI: uaddr2) is about to exit, but has not yet handled the
702 internal state cleanup. Try again.
703 EDEADLK
705 (FUTEX_LOCK_PI, FUTEX_LOCK_PI2, FUTEX_TRYLOCK_PI, FUTEX_CMP_RE‐
706 QUEUE_PI) The futex word at uaddr is already locked by the
707 caller.
708 EDEADLK
710 (FUTEX_CMP_REQUEUE_PI) While requeueing a waiter to the PI futex
711 for the futex word at uaddr2, the kernel detected a deadlock.
712 EFAULT A required pointer argument (i.e., uaddr, uaddr2, or timeout)
714 did not point to a valid user-space address.
715 EINTR A FUTEX_WAIT or FUTEX_WAIT_BITSET operation was interrupted by a
717 signal (see signal(7)). Before Linux 2.6.22, this error could
718 also be returned for a spurious wakeup; since Linux 2.6.22, this
719 no longer happens.
720 EINVAL The operation in futex_op is one of those that employs a time‐
722 out, but the supplied timeout argument was invalid (tv_sec was
723 less than zero, or tv_nsec was not less than 1,000,000,000).
724 EINVAL The operation specified in futex_op employs one or both of the
726 pointers uaddr and uaddr2, but one of these does not point to a
727 valid object—that is, the address is not four-byte-aligned.
728 EINVAL (FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET) The bit mask supplied in
730 val3 is zero.
731 EINVAL (FUTEX_CMP_REQUEUE_PI) uaddr equals uaddr2 (i.e., an attempt was
733 made to requeue to the same futex).
734 EINVAL (FUTEX_FD) The signal number supplied in val is invalid.
736 EINVAL (FUTEX_WAKE, FUTEX_WAKE_OP, FUTEX_WAKE_BITSET, FUTEX_REQUEUE,
738 FUTEX_CMP_REQUEUE) The kernel detected an inconsistency between
739 the user-space state at uaddr and the kernel state—that is, it
740 detected a waiter which waits in FUTEX_LOCK_PI or FUTEX_LOCK_PI2
741 on uaddr.
742 EINVAL (FUTEX_LOCK_PI, FUTEX_LOCK_PI2, FUTEX_TRYLOCK_PI, FUTEX_UN‐
744 LOCK_PI) The kernel detected an inconsistency between the user-
745 space state at uaddr and the kernel state. This indicates ei‐
746 ther state corruption or that the kernel found a waiter on uaddr
747 which is waiting via FUTEX_WAIT or FUTEX_WAIT_BITSET.
748 EINVAL (FUTEX_CMP_REQUEUE_PI) The kernel detected an inconsistency be‐
750 tween the user-space state at uaddr2 and the kernel state; that
751 is, the kernel detected a waiter which waits via FUTEX_WAIT or
752 FUTEX_WAIT_BITSET on uaddr2.
753 EINVAL (FUTEX_CMP_REQUEUE_PI) The kernel detected an inconsistency be‐
755 tween the user-space state at uaddr and the kernel state; that
756 is, the kernel detected a waiter which waits via FUTEX_WAIT or
757 FUTEX_WAIT_BITSET on uaddr.
758 EINVAL (FUTEX_CMP_REQUEUE_PI) The kernel detected an inconsistency be‐
760 tween the user-space state at uaddr and the kernel state; that
761 is, the kernel detected a waiter which waits on uaddr via FU‐
762 TEX_LOCK_PI or FUTEX_LOCK_PI2 (instead of FUTEX_WAIT_RE‐
763 QUEUE_PI).
764 EINVAL (FUTEX_CMP_REQUEUE_PI) An attempt was made to requeue a waiter
766 to a futex other than that specified by the matching FU‐
767 TEX_WAIT_REQUEUE_PI call for that waiter.
768 EINVAL (FUTEX_CMP_REQUEUE_PI) The val argument is not 1.
770 EINVAL Invalid argument.
772 ENFILE (FUTEX_FD) The system-wide limit on the total number of open
774 files has been reached.
775 ENOMEM (FUTEX_LOCK_PI, FUTEX_LOCK_PI2, FUTEX_TRYLOCK_PI, FUTEX_CMP_RE‐
777 QUEUE_PI) The kernel could not allocate memory to hold state in‐
778 formation.
779 ENOSYS Invalid operation specified in futex_op.
781 ENOSYS The FUTEX_CLOCK_REALTIME option was specified in futex_op, but
783 the accompanying operation was neither FUTEX_WAIT, FU‐
784 TEX_WAIT_BITSET, FUTEX_WAIT_REQUEUE_PI, nor FUTEX_LOCK_PI2.
785 ENOSYS (FUTEX_LOCK_PI, FUTEX_LOCK_PI2, FUTEX_TRYLOCK_PI, FUTEX_UN‐
787 LOCK_PI, FUTEX_CMP_REQUEUE_PI, FUTEX_WAIT_REQUEUE_PI) A run-time
788 check determined that the operation is not available. The PI-
789 futex operations are not implemented on all architectures and
790 are not supported on some CPU variants.
791 EPERM (FUTEX_LOCK_PI, FUTEX_LOCK_PI2, FUTEX_TRYLOCK_PI, FUTEX_CMP_RE‐
793 QUEUE_PI) The caller is not allowed to attach itself to the fu‐
794 tex at uaddr (for FUTEX_CMP_REQUEUE_PI: the futex at uaddr2).
795 (This may be caused by a state corruption in user space.)
796 EPERM (FUTEX_UNLOCK_PI) The caller does not own the lock represented
798 by the futex word.
799 ESRCH (FUTEX_LOCK_PI, FUTEX_LOCK_PI2, FUTEX_TRYLOCK_PI, FUTEX_CMP_RE‐
801 QUEUE_PI) The thread ID in the futex word at uaddr does not ex‐
802 ist.
803 ESRCH (FUTEX_CMP_REQUEUE_PI) The thread ID in the futex word at uaddr2
805 does not exist.
806 ETIMEDOUT
808 The operation in futex_op employed the timeout specified in
809 timeout, and the timeout expired before the operation completed.
810
812 Linux.
813
815 Linux 2.6.0.
816 Initial futex support was merged in Linux 2.5.7 but with different se‐
818 mantics from what was described above. A four-argument system call
819 with the semantics described in this page was introduced in Linux
820 2.5.40. A fifth argument was added in Linux 2.5.70, and a sixth argu‐
821 ment was added in Linux 2.6.7.
822
824 The program below demonstrates use of futexes in a program where a par‐
825 ent process and a child process use a pair of futexes located inside a
826 shared anonymous mapping to synchronize access to a shared resource:
827 the terminal. The two processes each write nloops (a command-line ar‐
828 gument that defaults to 5 if omitted) messages to the terminal and em‐
829 ploy a synchronization protocol that ensures that they alternate in
830 writing messages. Upon running this program we see output such as the
831 following:
832 $ ./futex_demo
834 Parent (18534) 0
835 Child (18535) 0
836 Parent (18534) 1
837 Child (18535) 1
838 Parent (18534) 2
839 Child (18535) 2
840 Parent (18534) 3
841 Child (18535) 3
842 Parent (18534) 4
843 Child (18535) 4
844 Program source
846 /* futex_demo.c
848 Usage: futex_demo [nloops]
850 (Default: 5)
851 Demonstrate the use of futexes in a program where parent and child
853 use a pair of futexes located inside a shared anonymous mapping to
854 synchronize access to a shared resource: the terminal. The two
855 processes each write 'num-loops' messages to the terminal and employ
856 a synchronization protocol that ensures that they alternate in
857 writing messages.
858 */
859 #define _GNU_SOURCE
860 #include <err.h>
861 #include <errno.h>
862 #include <linux/futex.h>
863 #include <stdatomic.h>
864 #include <stdint.h>
865 #include <stdio.h>
866 #include <stdlib.h>
867 #include <sys/mman.h>
868 #include <sys/syscall.h>
869 #include <sys/time.h>
870 #include <sys/wait.h>
871 #include <unistd.h>
872 static uint32_t *futex1, *futex2, *iaddr;
874 static int
876 futex(uint32_t *uaddr, int futex_op, uint32_t val,
877 const struct timespec *timeout, uint32_t *uaddr2, uint32_t val3)
878 {
879 return syscall(SYS_futex, uaddr, futex_op, val,
880 timeout, uaddr2, val3);
881 }
882 /* Acquire the futex pointed to by 'futexp': wait for its value to
884 become 1, and then set the value to 0. */
885 static void
887 fwait(uint32_t *futexp)
888 {
889 long s;
890 const uint32_t one = 1;
891 /* atomic_compare_exchange_strong(ptr, oldval, newval)
893 atomically performs the equivalent of:
894 if (*ptr == *oldval)
896 *ptr = newval;
897 It returns true if the test yielded true and *ptr was updated. */
899 while (1) {
901 /* Is the futex available? */
903 if (atomic_compare_exchange_strong(futexp, &one, 0))
904 break; /* Yes */
905 /* Futex is not available; wait. */
907 s = futex(futexp, FUTEX_WAIT, 0, NULL, NULL, 0);
909 if (s == -1 && errno != EAGAIN)
910 err(EXIT_FAILURE, "futex-FUTEX_WAIT");
911 }
912 }
913 /* Release the futex pointed to by 'futexp': if the futex currently
915 has the value 0, set its value to 1 and then wake any futex waiters,
916 so that if the peer is blocked in fwait(), it can proceed. */
917 static void
919 fpost(uint32_t *futexp)
920 {
921 long s;
922 const uint32_t zero = 0;
923 /* atomic_compare_exchange_strong() was described
925 in comments above. */
926 if (atomic_compare_exchange_strong(futexp, &zero, 1)) {
928 s = futex(futexp, FUTEX_WAKE, 1, NULL, NULL, 0);
929 if (s == -1)
930 err(EXIT_FAILURE, "futex-FUTEX_WAKE");
931 }
932 }
933 int
935 main(int argc, char *argv[])
936 {
937 pid_t childPid;
938 unsigned int nloops;
939 setbuf(stdout, NULL);
941 nloops = (argc > 1) ? atoi(argv[1]) : 5;
943 /* Create a shared anonymous mapping that will hold the futexes.
945 Since the futexes are being shared between processes, we
946 subsequently use the "shared" futex operations (i.e., not the
947 ones suffixed "_PRIVATE"). */
948 iaddr = mmap(NULL, sizeof(*iaddr) * 2, PROT_READ | PROT_WRITE,
950 MAP_ANONYMOUS | MAP_SHARED, -1, 0);
951 if (iaddr == MAP_FAILED)
952 err(EXIT_FAILURE, "mmap");
953 futex1 = &iaddr[0];
955 futex2 = &iaddr[1];
956 *futex1 = 0; /* State: unavailable */
958 *futex2 = 1; /* State: available */
959 /* Create a child process that inherits the shared anonymous
961 mapping. */
962 childPid = fork();
964 if (childPid == -1)
965 err(EXIT_FAILURE, "fork");
966 if (childPid == 0) { /* Child */
968 for (unsigned int j = 0; j < nloops; j++) {
969 fwait(futex1);
970 printf("Child (%jd) %u\n", (intmax_t) getpid(), j);
971 fpost(futex2);
972 }
973 exit(EXIT_SUCCESS);
975 }
976 /* Parent falls through to here. */
978 for (unsigned int j = 0; j < nloops; j++) {
980 fwait(futex2);
981 printf("Parent (%jd) %u\n", (intmax_t) getpid(), j);
982 fpost(futex1);
983 }
984 wait(NULL);
986 exit(EXIT_SUCCESS);
988 }
989
991 get_robust_list(2), restart_syscall(2), pthread_mutexattr_getproto‐
992 col(3), futex(7), sched(7)
993 The following kernel source files:
995 • Documentation/pi-futex.txt
997 • Documentation/futex-requeue-pi.txt
999 • Documentation/locking/rt-mutex.txt
1001 • Documentation/locking/rt-mutex-design.txt
1003 • Documentation/robust-futex-ABI.txt
1005 Franke, H., Russell, R., and Kirwood, M., 2002. Fuss, Futexes and Fur‐
1007 wocks: Fast Userlevel Locking in Linux (from proceedings of the Ottawa
1008 Linux Symposium 2002),
1009 ⟨http://kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf⟩
1010 Hart, D., 2009. A futex overview and update,
1012 ⟨http://lwn.net/Articles/360699/⟩
1013 Hart, D. and Guniguntala, D., 2009. Requeue-PI: Making glibc Condvars
1015 PI-Aware (from proceedings of the 2009 Real-Time Linux Workshop),
1016 ⟨http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf⟩
1017 Drepper, U., 2011. Futexes Are Tricky,
1019 ⟨http://www.akkadia.org/drepper/futex.pdf⟩
1020 Futex example library, futex-*.tar.bz2 at
1022 ⟨https://mirrors.kernel.org/pub/linux/kernel/people/rusty/⟩
1023Linux man-pages 6.04 2023-03-30 futex(2)