Debian Codegraph @

upstream/debian-unstable/man2/futex.2

raw
1 .\" Copyright 2015, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
5 .\" may be freely modified and distributed
6 .\" %%%LICENSE_END
7 .\"
8 .\" FIXME Still to integrate are some points from Torvald Riegel's mail of
9 .\" 2015-01-23:
10 .\" https://lore.kernel.org/lkml/[email protected]
11 .\"
12 .\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail
13 .\" https://lore.kernel.org/lkml/[email protected]
14 .\"
15 .TH futex 2 2026-02-14 "Linux man-pages 6.18"
16 .SH NAME
17 futex \- fast user-space locking
18 .SH LIBRARY
19 Standard C library
20 .RI ( libc ,\~ \-lc )
21 .SH SYNOPSIS
22 .nf
23 .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
24 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
25 .B #include <unistd.h>
26 .P
27 .BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " op ", ...);"
28 .fi
29 .SH DESCRIPTION
30 The
31 .BR futex ()
32 system call provides a method for waiting until a certain condition becomes
33 true.
34 It is typically used as a blocking construct in the context of
35 shared-memory synchronization.
36 When using futexes, the majority of
37 the synchronization operations are performed in user space.
38 A user-space program employs the
39 .BR futex ()
40 system call only when it is likely that the program has to block for
41 a longer time until the condition becomes true.
42 Other
43 .BR futex ()
44 operations can be used to wake any processes or threads waiting
45 for a particular condition.
46 .P
47 A futex is a 32-bit value\[em]referred to below as a
48 .IR "futex word" \[em]whose
49 address is supplied to the
50 .BR futex ()
51 system call.
52 (Futexes are 32 bits in size on all platforms, including 64-bit systems.)
53 All futex operations are governed by this value.
54 In order to share a futex between processes,
55 the futex is placed in a region of shared memory,
56 created using (for example)
57 .BR mmap (2)
58 or
59 .BR shmat (2).
60 (Thus, the futex word may have different
61 virtual addresses in different processes,
62 but these addresses all refer to the same location in physical memory.)
63 In a multithreaded program, it is sufficient to place the futex word
64 in a global variable shared by all threads.
65 .P
66 When executing a futex operation that requests to block a thread,
67 the kernel will block only if the futex word has the value that the
68 calling thread supplied (as one of the arguments of the
69 .BR futex ()
70 call) as the expected value of the futex word.
71 The loading of the futex word's value,
72 the comparison of that value with the expected value,
73 and the actual blocking will happen atomically and will be totally ordered
74 with respect to concurrent operations performed by other threads
75 on the same futex word.
76 .\" Notes from Darren Hart (Dec 2015):
77 .\" Totally ordered with respect futex operations refers to semantics
78 .\" of the ACQUIRE/RELEASE operations and how they impact ordering of
79 .\" memory reads and writes. The kernel futex operations are protected
80 .\" by spinlocks, which ensure that all operations are serialized
81 .\" with respect to one another.
82 .\"
83 .\" This is a lot to attempt to define in this document. Perhaps a
84 .\" reference to linux/Documentation/memory-barriers.txt as a footnote
85 .\" would be sufficient? Or perhaps for this manual, "serialized" would
86 .\" be sufficient, with a footnote regarding "totally ordered" and a
87 .\" pointer to the memory-barrier documentation?
88 Thus, the futex word is used to connect the synchronization in user space
89 with the implementation of blocking by the kernel.
90 Analogously to an atomic
91 compare-and-exchange operation that potentially changes shared memory,
92 blocking via a futex is an atomic compare-and-block operation.
93 .\" FIXME(Torvald Riegel):
94 .\" Eventually we want to have some text in NOTES to satisfy
95 .\" the reference in the following sentence
96 .\" See NOTES for a detailed specification of
97 .\" the synchronization semantics.
98 .P
99 One use of futexes is for implementing locks.
100 The state of the lock (i.e., acquired or not acquired)
101 can be represented as an atomically accessed flag in shared memory.
102 In the uncontended case,
103 a thread can access or modify the lock state with atomic instructions,
104 for example atomically changing it from not acquired to acquired
105 using an atomic compare-and-exchange instruction.
106 (Such instructions are performed entirely in user mode,
107 and the kernel maintains no information about the lock state.)
108 On the other hand, a thread may be unable to acquire a lock because
109 it is already acquired by another thread.
110 It then may pass the lock's flag as a futex word and the value
111 representing the acquired state as the expected value to a
112 .BR futex ()
113 wait operation.
114 This
115 .BR futex ()
116 operation will block if and only if the lock is still acquired
117 (i.e., the value in the futex word still matches the "acquired state").
118 When releasing the lock, a thread has to first reset the
119 lock state to not acquired and then execute a futex
120 operation that wakes threads blocked on the lock flag used as a futex word
121 (this can be further optimized to avoid unnecessary wake-ups).
122 See
123 .BR futex (7)
124 for more detail on how to use futexes.
125 .P
126 Besides the basic wait and wake-up futex functionality, there are further
127 futex operations aimed at supporting more complex use cases.
128 .P
129 Note that
130 no explicit initialization or destruction is necessary to use futexes;
131 the kernel maintains a futex
132 (i.e., the kernel-internal implementation artifact)
133 only while operations such as
134 .BR FUTEX_WAIT (2const)
135 are being performed on a particular futex word.
136 .\"
137 .SS Arguments
138 The
139 .I uaddr
140 argument points to the futex word.
141 On all platforms, futexes are four-byte
142 integers that must be aligned on a four-byte boundary.
143 The operation to perform on the futex is specified in the
144 .I op
145 argument.
146 .\"
147 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
148 .\"
149 .SS Futex operations
150 The
151 .I op
152 argument consists of two parts:
153 a command that specifies the operation to be performed,
154 bitwise ORed with zero or more options that
155 modify the behavior of the operation.
156 The options that may be included in
157 .I op
158 are as follows:
159 .TP
160 .BR FUTEX_PRIVATE_FLAG " (since Linux 2.6.22)"
161 .\" commit 34f01cc1f512fa783302982776895c73714ebbc2
162 This option bit can be employed with all futex operations.
163 It tells the kernel that the futex is process-private and not shared
164 with another process (i.e., it is being used for synchronization
165 only between threads of the same process).
166 This allows the kernel to make some additional performance optimizations.
167 .\" I.e., It allows the kernel choose the fast path for validating
168 .\" the user-space address and avoids expensive VMA lookups,
169 .\" taking reference counts on file backing store, and so on.
170 .IP
171 As a convenience,
172 .I <linux/futex.h>
173 defines a set of constants with the suffix
174 .B _PRIVATE
175 that are equivalents of all of the operations listed below,
176 .\" except the obsolete FUTEX_FD(2const), for which the "private" flag was
177 .\" meaningless
178 but with the
179 .B FUTEX_PRIVATE_FLAG
180 ORed into the constant value.
181 Thus, there are
182 .BR FUTEX_WAIT_PRIVATE ,
183 .BR FUTEX_WAKE_PRIVATE ,
184 and so on.
185 .TP
186 .BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)"
187 .\" commit 1acdac104668a0834cfa267de9946fac7764d486
188 This option bit can be employed only with the
189 .BR FUTEX_WAIT_BITSET (2const),
190 .BR FUTEX_WAIT_REQUEUE_PI (2const),
191 (since Linux 4.5)
192 .\" commit 337f13046ff03717a9e99675284a817527440a49
193 .BR FUTEX_WAIT (2const),
194 and
195 (since Linux 5.14)
196 .\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
197 .BR FUTEX_LOCK_PI2 (2const)
198 operations.
199 .IP
200 If this option is set, the kernel measures the
201 .I timeout
202 against the
203 .B CLOCK_REALTIME
204 clock.
205 .IP
206 If this option is not set, the kernel measures the
207 .I timeout
208 against the
209 .B CLOCK_MONOTONIC
210 clock.
211 .P
212 The operation specified in
213 .I op
214 is one of the following:
215 .\"
216 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
217 .\"
218 .TP
219 .BR FUTEX_WAIT (2const)
220 .TQ
221 .BR FUTEX_WAKE (2const)
222 .TQ
223 .BR FUTEX_FD (2const)
224 .TQ
225 .BR FUTEX_REQUEUE (2const)
226 .TQ
227 .BR FUTEX_CMP_REQUEUE (2const)
228 .TQ
229 .BR FUTEX_WAKE_OP (2const)
230 .TQ
231 .BR FUTEX_WAIT_BITSET (2const)
232 .TQ
233 .BR FUTEX_WAKE_BITSET (2const)
234 .\"
235 .SS Priority-inheritance futexes
236 Linux supports priority-inheritance (PI) futexes in order to handle
237 priority-inversion problems that can be encountered with
238 normal futex locks.
239 Priority inversion is the problem that occurs when a high-priority
240 task is blocked waiting to acquire a lock held by a low-priority task,
241 while tasks at an intermediate priority continuously preempt
242 the low-priority task from the CPU.
243 Consequently, the low-priority task makes no progress toward
244 releasing the lock, and the high-priority task remains blocked.
245 .P
246 Priority inheritance is a mechanism for dealing with
247 the priority-inversion problem.
248 With this mechanism, when a high-priority task becomes blocked
249 by a lock held by a low-priority task,
250 the priority of the low-priority task is temporarily raised
251 to that of the high-priority task,
252 so that it is not preempted by any intermediate level tasks,
253 and can thus make progress toward releasing the lock.
254 To be effective, priority inheritance must be transitive,
255 meaning that if a high-priority task blocks on a lock
256 held by a lower-priority task that is itself blocked by a lock
257 held by another intermediate-priority task
258 (and so on, for chains of arbitrary length),
259 then both of those tasks
260 (or more generally, all of the tasks in a lock chain)
261 have their priorities raised to be the same as the high-priority task.
262 .P
263 From a user-space perspective,
264 what makes a futex PI-aware is a policy agreement (described below)
265 between user space and the kernel about the value of the futex word,
266 coupled with the use of the PI-futex operations described below.
267 (Unlike the other futex operations described above,
268 the PI-futex operations are designed
269 for the implementation of very specific IPC mechanisms.)
270 .\"
271 .\" Quoting Darren Hart:
272 .\" These opcodes paired with the PI futex value policy (described below)
273 .\" defines a "futex" as PI aware. These were created very specifically
274 .\" in support of PI pthread_mutexes, so it makes a lot more sense to
275 .\" talk about a PI aware pthread_mutex, than a PI aware futex, since
276 .\" there is a lot of policy and scaffolding that has to be built up
277 .\" around it to use it properly (this is what a PI pthread_mutex is).
278 .P
279 .\" mtk: The following text is drawn from the Hart/Guniguntala paper
280 .\" (listed in SEE ALSO), but I have reworded some pieces
281 .\" significantly.
282 .\"
283 The PI-futex operations described below differ from the other
284 futex operations in that they impose policy on the use of the value of the
285 futex word:
286 .IP \[bu] 3
287 If the lock is not acquired, the futex word's value shall be 0.
288 .IP \[bu]
289 If the lock is acquired, the futex word's value shall
290 be the thread ID (TID;
291 see
292 .BR gettid (2))
293 of the owning thread.
294 .IP \[bu]
295 If the lock is owned and there are threads contending for the lock,
296 then the
297 .B FUTEX_WAITERS
298 bit shall be set in the futex word's value;
299 in other words,
300 this value is:
301 .IP
302 .in +4n
303 .EX
304 FUTEX_WAITERS | TID
305 .EE
306 .in
307 .IP
308 (Note that is invalid for a PI futex word to have no owner and
309 .B FUTEX_WAITERS
310 set.)
311 .P
312 With this policy in place,
313 a user-space application can acquire an unacquired
314 lock or release a lock using atomic instructions executed in user mode
315 (e.g., a compare-and-swap operation such as
316 .I cmpxchg
317 on the x86 architecture).
318 Acquiring a lock simply consists of using compare-and-swap to atomically
319 set the futex word's value to the caller's TID if its previous value was 0.
320 Releasing a lock requires using compare-and-swap to set the futex word's
321 value to 0 if the previous value was the expected TID.
322 .P
323 If a futex is already acquired (i.e., has a nonzero value),
324 waiters must employ the
325 .BR FUTEX_LOCK_PI (2const)
326 or
327 .BR FUTEX_LOCK_PI2 (2const)
328 operations to acquire the lock.
329 If other threads are waiting for the lock, then the
330 .B FUTEX_WAITERS
331 bit is set in the futex value;
332 in this case, the lock owner must employ the
333 .BR FUTEX_UNLOCK_PI (2const)
334 operation to release the lock.
335 .P
336 In the cases where callers are forced into the kernel
337 (i.e., required to perform a
338 .BR futex ()
339 call),
340 they then deal directly with a so-called RT-mutex,
341 a kernel locking mechanism which implements the required
342 priority-inheritance semantics.
343 After the RT-mutex is acquired, the futex value is updated accordingly,
344 before the calling thread returns to user space.
345 .P
346 It is important to note
347 .\" tglx (July 2015):
348 .\" If there are multiple waiters on a pi futex then a wake pi operation
349 .\" will wake the first waiter and hand over the lock to this waiter. This
350 .\" includes handing over the rtmutex which represents the futex in the
351 .\" kernel. The strict requirement is that the futex owner and the rtmutex
352 .\" owner must be the same, except for the update period which is
353 .\" serialized by the futex internal locking. That means the kernel must
354 .\" update the user-space value prior to returning to user space
355 that the kernel will update the futex word's value prior
356 to returning to user space.
357 (This prevents the possibility of the futex word's value ending
358 up in an invalid state, such as having an owner but the value being 0,
359 or having waiters but not having the
360 .B FUTEX_WAITERS
361 bit set.)
362 .P
363 If a futex has an associated RT-mutex in the kernel
364 (i.e., there are blocked waiters)
365 and the owner of the futex/RT-mutex dies unexpectedly,
366 then the kernel cleans up the RT-mutex and hands it over to the next waiter.
367 This in turn requires that the user-space value is updated accordingly.
368 To indicate that this is required, the kernel sets the
369 .B FUTEX_OWNER_DIED
370 bit in the futex word along with the thread ID of the new owner.
371 User space can detect this situation via the presence of the
372 .B FUTEX_OWNER_DIED
373 bit and is then responsible for cleaning up the stale state left over by
374 the dead owner.
375 .\" tglx (July 2015):
376 .\" The FUTEX_OWNER_DIED bit can also be set on uncontended futexes, where
377 .\" the kernel has no state associated. This happens via the robust futex
378 .\" mechanism. In that case the futex value will be set to
379 .\" FUTEX_OWNER_DIED. The robust futex mechanism is also available for non
380 .\" PI futexes.
381 .P
382 PI futexes are operated on by specifying one of the values listed below in
383 .IR op .
384 Note that the PI futex operations must be used as paired operations
385 and are subject to some additional requirements:
386 .IP \[bu] 3
387 .BR FUTEX_LOCK_PI (2const),
388 .BR FUTEX_LOCK_PI2 (2const),
389 and
390 .BR FUTEX_TRYLOCK_PI (2const)
391 pair with
392 .BR FUTEX_UNLOCK_PI (2const).
393 .BR FUTEX_UNLOCK_PI (2const)
394 must be called only on a futex owned by the calling thread,
395 as defined by the value policy, otherwise the error
396 .B EPERM
397 results.
398 .IP \[bu]
399 .BR FUTEX_WAIT_REQUEUE_PI (2const)
400 pairs with
401 .BR FUTEX_CMP_REQUEUE_PI (2const).
402 This must be performed from a non-PI futex to a distinct PI futex
403 (or the error
404 .B EINVAL
405 results).
406 Additionally,
407 the number of waiters to be woken must be 1
408 (or the error
409 .B EINVAL
410 results).
411 .P
412 The PI futex operations are as follows:
413 .\"
414 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
415 .\"
416 .TP
417 .BR FUTEX_LOCK_PI (2const)
418 .TQ
419 .BR FUTEX_LOCK_PI2 (2const)
420 .TQ
421 .BR FUTEX_TRYLOCK_PI (2const)
422 .TQ
423 .BR FUTEX_UNLOCK_PI (2const)
424 .TQ
425 .BR FUTEX_CMP_REQUEUE_PI (2const)
426 .TQ
427 .BR FUTEX_WAIT_REQUEUE_PI (2const)
428 .P
429 The
430 .BR FUTEX_WAIT_REQUEUE_PI (2const)
431 and
432 .BR FUTEX_CMP_REQUEUE_PI (2const)
433 were added to support a fairly specific use case:
434 support for priority-inheritance-aware POSIX threads condition variables.
435 The idea is that these operations should always be paired,
436 in order to ensure that user space and the kernel remain in sync.
437 Thus, in the
438 .BR FUTEX_WAIT_REQUEUE_PI (2const)
439 operation, the user-space application pre-specifies the target
440 of the requeue that takes place in the
441 .BR FUTEX_CMP_REQUEUE_PI (2const)
442 operation.
443 .\"
444 .\" Darren Hart notes that a patch to allow glibc to fully support
445 .\" PI-aware pthreads condition variables has not yet been accepted into
446 .\" glibc. The story is complex, and can be found at
447 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=11588
448 .\" Darren notes that in the meantime, the patch is shipped with various
449 .\" PREEMPT_RT-enabled Linux systems.
450 .\"
451 .\" Related to the preceding, Darren proposed that somewhere, man-pages
452 .\" should document the following point:
453 .\"
454 .\" While the Linux kernel, since Linux 2.6.31, supports requeueing of
455 .\" priority-inheritance (PI) aware mutexes via the
456 .\" FUTEX_WAIT_REQUEUE_PI and FUTEX_CMP_REQUEUE_PI futex operations,
457 .\" the glibc implementation does not yet take full advantage of this.
458 .\" Specifically, the condvar internal data lock remains a non-PI aware
459 .\" mutex, regardless of the type of the pthread_mutex associated with
460 .\" the condvar. This can lead to an unbounded priority inversion on
461 .\" the internal data lock even when associating a PI aware
462 .\" pthread_mutex with a condvar during a pthread_cond*_wait
463 .\" operation. For this reason, it is not recommended to rely on
464 .\" priority inheritance when using pthread condition variables.
465 .\"
466 .\" The problem is that the obvious location for this text is
467 .\" the pthread_cond*wait(3) man page. However, such a man page
468 .\" does not currently exist.
469 .\"
470 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
471 .\"
472 .SH RETURN VALUE
473 On error,
474 \-1 is returned,
475 and
476 .I errno
477 is set to indicate the error.
478 .P
479 The return value on success depends on the operation.
480 .\"
481 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
482 .\"
483 .SH ERRORS
484 .TP
485 .B EACCES
486 No read access to the memory of a futex word.
487 .TP
488 .B EFAULT
489 .I uaddr
490 did not point to a valid user-space address.
491 .TP
492 .B EINVAL
493 .I uaddr
494 does not point to a valid object\[em]that is,
495 the address is not four-byte-aligned.
496 .TP
497 .B EINVAL
498 Invalid argument.
499 .TP
500 .B ENOSYS
501 Invalid operation specified in
502 .IR op .
503 .TP
504 .B ENOSYS
505 The
506 .B FUTEX_CLOCK_REALTIME
507 option was specified in
508 .IR op ,
509 but the accompanying operation was neither
510 .BR FUTEX_WAIT_BITSET (2const),
511 .BR FUTEX_WAIT_REQUEUE_PI (2const),
512 nor
513 .BR FUTEX_LOCK_PI2 (2const).
514 .\"
515 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
516 .\"
517 .SH STANDARDS
518 Linux.
519 .SH HISTORY
520 Linux 2.6.0.
521 .P
522 Initial futex support was merged in Linux 2.5.7 but with different
523 semantics from what was described above.
524 A four-argument system call with the semantics
525 described in this page was introduced in Linux 2.5.40.
526 A fifth argument was added in Linux 2.5.70,
527 and a sixth argument was added in Linux 2.6.7.
528 .SH EXAMPLES
529 The program below demonstrates use of futexes in a program where a parent
530 process and a child process use a pair of futexes located inside a
531 shared anonymous mapping to synchronize access to a shared resource:
532 the terminal.
533 The two processes each write
534 .I nloops
535 (a command-line argument that defaults to 5 if omitted)
536 messages to the terminal and employ a synchronization protocol
537 that ensures that they alternate in writing messages.
538 Upon running this program we see output such as the following:
539 .P
540 .in +4n
541 .EX
542 .RB $ " ./futex_demo" ;
543 Parent (18534) 0
544 Child (18535) 0
545 Parent (18534) 1
546 Child (18535) 1
547 Parent (18534) 2
548 Child (18535) 2
549 Parent (18534) 3
550 Child (18535) 3
551 Parent (18534) 4
552 Child (18535) 4
553 .EE
554 .in
555 .SS Program source
556 \&
557 .\" SRC BEGIN (futex.c)
558 .EX
559 /* futex_demo.c
560 \&
561 Usage: futex_demo [nloops]
562 (Default: 5)
563 \&
564 Demonstrate the use of futexes in a program where parent and child
565 use a pair of futexes located inside a shared anonymous mapping to
566 synchronize access to a shared resource: the terminal. The two
567 processes each write \[aq]num\-loops\[aq] messages to the terminal and employ
568 a synchronization protocol that ensures that they alternate in
569 writing messages.
570 */
571 #define _GNU_SOURCE
572 #include <err.h>
573 #include <errno.h>
574 #include <linux/futex.h>
575 #include <stdatomic.h>
576 #include <stdint.h>
577 #include <stdio.h>
578 #include <stdlib.h>
579 #include <sys/mman.h>
580 #include <sys/syscall.h>
581 #include <sys/time.h>
582 #include <sys/wait.h>
583 #include <unistd.h>
584 \&
585 static uint32_t *futex1, *futex2, *iaddr;
586 \&
587 static int
588 futex(uint32_t *uaddr, int op, uint32_t val,
589 const struct timespec *timeout, uint32_t *uaddr2, uint32_t val3)
590 {
591 return syscall(SYS_futex, uaddr, op, val,
592 timeout, uaddr2, val3);
593 }
594 \&
595 /* Acquire the futex pointed to by \[aq]futexp\[aq]: wait for its value to
596 become 1, and then set the value to 0. */
597 \&
598 static void
599 fwait(uint32_t *futexp)
600 {
601 long s;
602 const uint32_t one = 1;
603 \&
604 /* atomic_compare_exchange_strong(ptr, oldval, newval)
605 atomically performs the equivalent of:
606 \&
607 if (*ptr == *oldval)
608 *ptr = newval;
609 \&
610 It returns true if the test yielded true and *ptr was updated. */
611 \&
612 for (;;) {
613 \&
614 /* Is the futex available? */
615 if (atomic_compare_exchange_strong(futexp, &one, 0))
616 break; /* Yes */
617 \&
618 /* Futex is not available; wait. */
619 \&
620 s = futex(futexp, FUTEX_WAIT, 0, NULL, NULL, 0);
621 if (s == \-1 && errno != EAGAIN)
622 err(EXIT_FAILURE, "futex\-FUTEX_WAIT");
623 }
624 }
625 \&
626 /* Release the futex pointed to by \[aq]futexp\[aq]: if the futex currently
627 has the value 0, set its value to 1 and then wake any futex waiters,
628 so that if the peer is blocked in fwait(), it can proceed. */
629 \&
630 static void
631 fpost(uint32_t *futexp)
632 {
633 long s;
634 const uint32_t zero = 0;
635 \&
636 /* atomic_compare_exchange_strong() was described
637 in comments above. */
638 \&
639 if (atomic_compare_exchange_strong(futexp, &zero, 1)) {
640 s = futex(futexp, FUTEX_WAKE, 1, NULL, NULL, 0);
641 if (s == \-1)
642 err(EXIT_FAILURE, "futex\-FUTEX_WAKE");
643 }
644 }
645 \&
646 int
647 main(int argc, char *argv[])
648 {
649 pid_t childPid;
650 unsigned int nloops;
651 \&
652 setbuf(stdout, NULL);
653 \&
654 nloops = (argc > 1) ? atoi(argv[1]) : 5;
655 \&
656 /* Create a shared anonymous mapping that will hold the futexes.
657 Since the futexes are being shared between processes, we
658 subsequently use the "shared" futex operations (i.e., not the
659 ones suffixed "_PRIVATE"). */
660 \&
661 iaddr = mmap(NULL, sizeof(*iaddr) * 2, PROT_READ | PROT_WRITE,
662 MAP_ANONYMOUS | MAP_SHARED, \-1, 0);
663 if (iaddr == MAP_FAILED)
664 err(EXIT_FAILURE, "mmap");
665 \&
666 futex1 = &iaddr[0];
667 futex2 = &iaddr[1];
668 \&
669 *futex1 = 0; /* State: unavailable */
670 *futex2 = 1; /* State: available */
671 \&
672 /* Create a child process that inherits the shared anonymous
673 mapping. */
674 \&
675 childPid = fork();
676 if (childPid == \-1)
677 err(EXIT_FAILURE, "fork");
678 \&
679 if (childPid == 0) { /* Child */
680 for (unsigned int j = 0; j < nloops; j++) {
681 fwait(futex1);
682 printf("Child (%jd) %u\[rs]n", (intmax_t) getpid(), j);
683 fpost(futex2);
684 }
685 \&
686 exit(EXIT_SUCCESS);
687 }
688 \&
689 /* Parent falls through to here. */
690 \&
691 for (unsigned int j = 0; j < nloops; j++) {
692 fwait(futex2);
693 printf("Parent (%jd) %u\[rs]n", (intmax_t) getpid(), j);
694 fpost(futex1);
695 }
696 \&
697 wait(NULL);
698 \&
699 exit(EXIT_SUCCESS);
700 }
701 .EE
702 .\" SRC END
703 .SH SEE ALSO
704 .ad l
705 .BR get_robust_list (2),
706 .BR restart_syscall (2),
707 .BR pthread_mutexattr_getprotocol (3),
708 .BR futex (7),
709 .BR sched (7)
710 .P
711 The following kernel source files:
712 .IP \[bu] 3
713 .I Documentation/locking/pi\-futex.rst
714 .IP \[bu]
715 .I Documentation/locking/futex\-requeue\-pi.rst
716 .IP \[bu]
717 .I Documentation/locking/rt\-mutex.rst
718 .IP \[bu]
719 .I Documentation/locking/rt\-mutex\-design.rst
720 .IP \[bu]
721 .I Documentation/robust\-futex\-ABI.rst
722 .P
723 Franke, H., Russell, R., and Kirwood, M., 2002.
724 .br
725 .UR http:\://kernel.org/\:doc/\:ols/\:2002/\:ols2002\-pages\-479\-495.pdf
726 .I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux
727 .UE
728 (from proceedings of the Ottawa Linux Symposium 2002).
729 .P
730 Hart, D., 2009.
731 .UR http:\://lwn.net/\:Articles/\:360699/
732 .I A futex overview and update
733 .UE .
734 .P
735 Hart, D.\& and Guniguntala, D., 2009.
736 .UR http:\://lwn.net/\:images/\:conf/\:rtlws11/\:papers/\:proc/\:p10.pdf
737 .I Requeue-PI: Making glibc Condvars PI-Aware
738 .UE
739 (from proceedings of the 2009 Real-Time Linux Workshop).
740 .P
741 Drepper, U., 2011.
742 .UR http:\://www.akkadia.org/\:drepper/\:futex.pdf
743 .I Futexes Are Tricky
744 .UE .
745 .P
746 Futex example library,
747 .UR https:\://mirrors.kernel.org/\:pub/\:linux/\:kernel/\:people/\:rusty/
748 futex\-*.tar.bz2
749 .UE .
750 .\"
751 .\" FIXME(Torvald) We should probably refer to the glibc code here, in
752 .\" particular the glibc-internal futex wrapper functions that are
753 .\" WIP, and the generic pthread_mutex_t and perhaps condvar
754 .\" implementations.