summaryrefslogtreecommitdiffstats
path: root/man2/futex.2
blob: 43b10754359ab4830fe8eab3080cdde457840551 (plain)
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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
.\" Page by b.hubert
.\" and Copyright (C) 2015, Thomas Gleixner <tglx@linutronix.de>
.\" and Copyright (C) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
.\" may be freely modified and distributed
.\" %%%LICENSE_END
.\"
.\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com)
.\" added ERRORS section.
.\"
.\" Modified 2004-06-17 mtk
.\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE
.\"
.\" FIXME Still to integrate are some points from Torvald Riegel's mail of
.\" 2015-01-23:
.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=7977
.\"
.\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail
.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242
.\"
.TH futex 2 2023-05-03 "Linux man-pages 6.05.01"
.SH NAME
futex \- fast user-space locking
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.PP
.BR "#include <linux/futex.h>" "      /* Definition of " FUTEX_* " constants */"
.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.PP
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \
", uint32_t " val ,
.BI "             const struct timespec *" timeout , \
" \fR  /* or: \fBuint32_t \fIval2\fP */"
.BI "             uint32_t *" uaddr2 ", uint32_t " val3 );
.fi
.PP
.IR Note :
glibc provides no wrapper for
.BR futex (),
necessitating the use of
.BR syscall (2).
.SH DESCRIPTION
The
.BR futex ()
system call provides a method for waiting until a certain condition becomes
true.
It is typically used as a blocking construct in the context of
shared-memory synchronization.
When using futexes, the majority of
the synchronization operations are performed in user space.
A user-space program employs the
.BR futex ()
system call only when it is likely that the program has to block for
a longer time until the condition becomes true.
Other
.BR futex ()
operations can be used to wake any processes or threads waiting
for a particular condition.
.PP
A futex is a 32-bit value\[em]referred to below as a
.IR "futex word" \[em]whose
address is supplied to the
.BR futex ()
system call.
(Futexes are 32 bits in size on all platforms, including 64-bit systems.)
All futex operations are governed by this value.
In order to share a futex between processes,
the futex is placed in a region of shared memory,
created using (for example)
.BR mmap (2)
or
.BR shmat (2).
(Thus, the futex word may have different
virtual addresses in different processes,
but these addresses all refer to the same location in physical memory.)
In a multithreaded program, it is sufficient to place the futex word
in a global variable shared by all threads.
.PP
When executing a futex operation that requests to block a thread,
the kernel will block only if the futex word has the value that the
calling thread supplied (as one of the arguments of the
.BR futex ()
call) as the expected value of the futex word.
The loading of the futex word's value,
the comparison of that value with the expected value,
and the actual blocking will happen atomically and will be totally ordered
with respect to concurrent operations performed by other threads
on the same futex word.
.\" Notes from Darren Hart (Dec 2015):
.\"     Totally ordered with respect futex operations refers to semantics
.\"     of the ACQUIRE/RELEASE operations and how they impact ordering of
.\"     memory reads and writes. The kernel futex operations are protected
.\"     by spinlocks, which ensure that all operations are serialized
.\"     with respect to one another.
.\"
.\"     This is a lot to attempt to define in this document. Perhaps a
.\"     reference to linux/Documentation/memory-barriers.txt as a footnote
.\"     would be sufficient? Or perhaps for this manual, "serialized" would
.\"     be sufficient, with a footnote regarding "totally ordered" and a
.\"     pointer to the memory-barrier documentation?
Thus, the futex word is used to connect the synchronization in user space
with the implementation of blocking by the kernel.
Analogously to an atomic
compare-and-exchange operation that potentially changes shared memory,
blocking via a futex is an atomic compare-and-block operation.
.\" FIXME(Torvald Riegel):
.\" Eventually we want to have some text in NOTES to satisfy
.\" the reference in the following sentence
.\"     See NOTES for a detailed specification of
.\"     the synchronization semantics.
.PP
One use of futexes is for implementing locks.
The state of the lock (i.e., acquired or not acquired)
can be represented as an atomically accessed flag in shared memory.
In the uncontended case,
a thread can access or modify the lock state with atomic instructions,
for example atomically changing it from not acquired to acquired
using an atomic compare-and-exchange instruction.
(Such instructions are performed entirely in user mode,
and the kernel maintains no information about the lock state.)
On the other hand, a thread may be unable to acquire a lock because
it is already acquired by another thread.
It then may pass the lock's flag as a futex word and the value
representing the acquired state as the expected value to a
.BR futex ()
wait operation.
This
.BR futex ()
operation will block if and only if the lock is still acquired
(i.e., the value in the futex word still matches the "acquired state").
When releasing the lock, a thread has to first reset the
lock state to not acquired and then execute a futex
operation that wakes threads blocked on the lock flag used as a futex word
(this can be further optimized to avoid unnecessary wake-ups).
See
.BR futex (7)
for more detail on how to use futexes.
.PP
Besides the basic wait and wake-up futex functionality, there are further
futex operations aimed at supporting more complex use cases.
.PP
Note that
no explicit initialization or destruction is necessary to use futexes;
the kernel maintains a futex
(i.e., the kernel-internal implementation artifact)
only while operations such as
.BR FUTEX_WAIT ,
described below, are being performed on a particular futex word.
.\"
.SS Arguments
The
.I uaddr
argument points to the futex word.
On all platforms, futexes are four-byte
integers that must be aligned on a four-byte boundary.
The operation to perform on the futex is specified in the
.I futex_op
argument;
.I val
is a value whose meaning and purpose depends on
.IR futex_op .
.PP
The remaining arguments
.RI ( timeout ,
.IR uaddr2 ,
and
.IR val3 )
are required only for certain of the futex operations described below.
Where one of these arguments is not required, it is ignored.
.PP
For several blocking operations, the
.I timeout
argument is a pointer to a
.I timespec
structure that specifies a timeout for the operation.
However,  notwithstanding the prototype shown above, for some operations,
the least significant four bytes of this argument are instead
used as an integer whose meaning is determined by the operation.
For these operations, the kernel casts the
.I timeout
value first to
.IR "unsigned long",
then to
.IR uint32_t ,
and in the remainder of this page, this argument is referred to as
.I val2
when interpreted in this fashion.
.PP
Where it is required, the
.I uaddr2
argument is a pointer to a second futex word that is employed
by the operation.
.PP
The interpretation of the final integer argument,
.IR val3 ,
depends on the operation.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.SS Futex operations
The
.I futex_op
argument consists of two parts:
a command that specifies the operation to be performed,
bitwise ORed with zero or more options that
modify the behaviour of the operation.
The options that may be included in
.I futex_op
are as follows:
.TP
.BR FUTEX_PRIVATE_FLAG " (since Linux 2.6.22)"
.\" commit 34f01cc1f512fa783302982776895c73714ebbc2
This option bit can be employed with all futex operations.
It tells the kernel that the futex is process-private and not shared
with another process (i.e., it is being used for synchronization
only between threads of the same process).
This allows the kernel to make some additional performance optimizations.
.\" I.e., It allows the kernel choose the fast path for validating
.\" the user-space address and avoids expensive VMA lookups,
.\" taking reference counts on file backing store, and so on.
.IP
As a convenience,
.I <linux/futex.h>
defines a set of constants with the suffix
.B _PRIVATE
that are equivalents of all of the operations listed below,
.\" except the obsolete FUTEX_FD, for which the "private" flag was
.\" meaningless
but with the
.B FUTEX_PRIVATE_FLAG
ORed into the constant value.
Thus, there are
.BR FUTEX_WAIT_PRIVATE ,
.BR FUTEX_WAKE_PRIVATE ,
and so on.
.TP
.BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)"
.\" commit 1acdac104668a0834cfa267de9946fac7764d486
This option bit can be employed only with the
.BR FUTEX_WAIT_BITSET ,
.BR FUTEX_WAIT_REQUEUE_PI ,
(since Linux 4.5)
.\" commit 337f13046ff03717a9e99675284a817527440a49
.BR FUTEX_WAIT ,
and
(since Linux 5.14)
.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
.B FUTEX_LOCK_PI2
operations.
.IP
If this option is set, the kernel measures the
.I timeout
against the
.B CLOCK_REALTIME
clock.
.IP
If this option is not set, the kernel measures the
.I timeout
against the
.B CLOCK_MONOTONIC
clock.
.PP
The operation specified in
.I futex_op
is one of the following:
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_WAIT " (since Linux 2.6.0)"
.\" Strictly speaking, since some time in Linux 2.5.x
This operation tests that the value at the
futex word pointed to by the address
.I uaddr
still contains the expected value
.IR val ,
and if so, then sleeps waiting for a
.B FUTEX_WAKE
operation on the futex word.
The load of the value of the futex word is an atomic memory
access (i.e., using atomic machine instructions of the respective
architecture).
This load, the comparison with the expected value, and
starting to sleep are performed atomically
.\" FIXME: Torvald, I think we may need to add some explanation of
.\" "totally ordered" here.
and totally ordered
with respect to other futex operations on the same futex word.
If the thread starts to sleep,
it is considered a waiter on this futex word.
If the futex value does not match
.IR val ,
then the call fails immediately with the error
.BR EAGAIN .
.IP
The purpose of the comparison with the expected value is to prevent lost
wake-ups.
If another thread changed the value of the futex word after the
calling thread decided to block based on the prior value,
and if the other thread executed a
.B FUTEX_WAKE
operation (or similar wake-up) after the value change and before this
.B FUTEX_WAIT
operation, then the calling thread will observe the
value change and will not start to sleep.
.IP
If the
.I timeout
is not NULL, the structure it points to specifies a
timeout for the wait.
(This interval will be rounded up to the system clock granularity,
and is guaranteed not to expire early.)
The timeout is by default measured according to the
.B CLOCK_MONOTONIC
clock, but, since Linux 4.5, the
.B CLOCK_REALTIME
clock can be selected by specifying
.B FUTEX_CLOCK_REALTIME
in
.IR futex_op .
If
.I timeout
is NULL, the call blocks indefinitely.
.IP
.IR Note :
for
.BR FUTEX_WAIT ,
.I timeout
is interpreted as a
.I relative
value.
This differs from other futex operations, where
.I timeout
is interpreted as an absolute value.
To obtain the equivalent of
.B FUTEX_WAIT
with an absolute timeout, employ
.B FUTEX_WAIT_BITSET
with
.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY .
.IP
The arguments
.I uaddr2
and
.I val3
are ignored.
.\" FIXME . (Torvald) I think we should remove this.  Or maybe adapt to a
.\" different example.
.\"
.\"     For
.\"     .BR futex (7),
.\"     this call is executed if decrementing the count gave a negative value
.\"     (indicating contention),
.\"     and will sleep until another process or thread releases
.\"     the futex and executes the
.\"     .B FUTEX_WAKE
.\"     operation.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_WAKE " (since Linux 2.6.0)"
.\" Strictly speaking, since Linux 2.5.x
This operation wakes at most
.I val
of the waiters that are waiting (e.g., inside
.BR FUTEX_WAIT )
on the futex word at the address
.IR uaddr .
Most commonly,
.I val
is specified as either 1 (wake up a single waiter) or
.B INT_MAX
(wake up all waiters).
No guarantee is provided about which waiters are awoken
(e.g., a waiter with a higher scheduling priority is not guaranteed
to be awoken in preference to a waiter with a lower priority).
.IP
The arguments
.IR timeout ,
.IR uaddr2 ,
and
.I val3
are ignored.
.\" FIXME . (Torvald) I think we should remove this.  Or maybe adapt to
.\" a different example.
.\"
.\"     For
.\"     .BR futex (7),
.\"     this is executed if incrementing the count showed that
.\"     there were waiters,
.\"     once the futex value has been set to 1
.\"     (indicating that it is available).
.\"
.\" How does "incrementing the count show that there were waiters"?
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_FD " (from Linux 2.6.0 up to and including Linux 2.6.25)"
.\" Strictly speaking, from Linux 2.5.x to Linux 2.6.25
This operation creates a file descriptor that is associated with
the futex at
.IR uaddr .
The caller must close the returned file descriptor after use.
When another process or thread performs a
.B FUTEX_WAKE
on the futex word, the file descriptor indicates as being readable with
.BR select (2),
.BR poll (2),
and
.BR epoll (7)
.IP
The file descriptor can be used to obtain asynchronous notifications: if
.I val
is nonzero, then, when another process or thread executes a
.BR FUTEX_WAKE ,
the caller will receive the signal number that was passed in
.IR val .
.IP
The arguments
.IR timeout ,
.IR uaddr2 ,
and
.I val3
are ignored.
.IP
Because it was inherently racy,
.B FUTEX_FD
has been removed
.\" commit 82af7aca56c67061420d618cc5a30f0fd4106b80
from Linux 2.6.26 onward.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_REQUEUE " (since Linux 2.6.0)"
This operation performs the same task as
.B FUTEX_CMP_REQUEUE
(see below), except that no check is made using the value in
.IR  val3 .
(The argument
.I val3
is ignored.)
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)"
This operation first checks whether the location
.I uaddr
still contains the value
.IR val3 .
If not, the operation fails with the error
.BR EAGAIN .
Otherwise, the operation wakes up a maximum of
.I val
waiters that are waiting on the futex at
.IR uaddr .
If there are more than
.I val
waiters, then the remaining waiters are removed
from the wait queue of the source futex at
.I uaddr
and added to the wait queue of the target futex at
.IR uaddr2 .
The
.I val2
argument specifies an upper limit on the number of waiters
that are requeued to the futex at
.IR uaddr2 .
.IP
.\" FIXME(Torvald) Is the following correct?  Or is just the decision
.\" which threads to wake or requeue part of the atomic operation?
The load from
.I uaddr
is an atomic memory access (i.e., using atomic machine instructions of
the respective architecture).
This load, the comparison with
.IR val3 ,
and the requeueing of any waiters are performed atomically and totally
ordered with respect to other operations on the same futex word.
.\" Notes from a f2f conversation with Thomas Gleixner (Aug 2015): ###
.\"	The operation is serialized with respect to operations on both
.\"	source and target futex. No other waiter can enqueue itself
.\"	for waiting and no other waiter can dequeue itself because of
.\"	a timeout or signal.
.IP
Typical values to specify for
.I val
are 0 or 1.
(Specifying
.B INT_MAX
is not useful, because it would make the
.B FUTEX_CMP_REQUEUE
operation equivalent to
.BR FUTEX_WAKE .)
The limit value specified via
.I val2
is typically either 1 or
.BR INT_MAX .
(Specifying the argument as 0 is not useful, because it would make the
.B FUTEX_CMP_REQUEUE
operation equivalent to
.BR FUTEX_WAIT .)
.IP
The
.B FUTEX_CMP_REQUEUE
operation was added as a replacement for the earlier
.BR FUTEX_REQUEUE .
The difference is that the check of the value at
.I uaddr
can be used to ensure that requeueing happens only under certain
conditions, which allows race conditions to be avoided in certain use cases.
.\" But, as Rich Felker points out, there remain valid use cases for
.\" FUTEX_REQUEUE, for example, when the calling thread is requeuing
.\" the target(s) to a lock that the calling thread owns
.\"     From: Rich Felker <dalias@libc.org>
.\"     Date: Wed, 29 Oct 2014 22:43:17 -0400
.\"     To: Darren Hart <dvhart@infradead.org>
.\"     CC: libc-alpha@sourceware.org, ...
.\"     Subject: Re: Add futex wrapper to glibc?
.IP
Both
.B FUTEX_REQUEUE
and
.B FUTEX_CMP_REQUEUE
can be used to avoid "thundering herd" wake-ups that could occur when using
.B FUTEX_WAKE
in cases where all of the waiters that are woken need to acquire
another futex.
Consider the following scenario,
where multiple waiter threads are waiting on B,
a wait queue implemented using a futex:
.IP
.in +4n
.EX
lock(A)
while (!check_value(V)) {
    unlock(A);
    block_on(B);
    lock(A);
};
unlock(A);
.EE
.in
.IP
If a waker thread used
.BR FUTEX_WAKE ,
then all waiters waiting on B would be woken up,
and they would all try to acquire lock A.
However, waking all of the threads in this manner would be pointless because
all except one of the threads would immediately block on lock A again.
By contrast, a requeue operation wakes just one waiter and moves
the other waiters to lock A,
and when the woken waiter unlocks A then the next waiter can proceed.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_WAKE_OP " (since Linux 2.6.14)"
.\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721
.\"	Author: Jakub Jelinek <jakub@redhat.com>
.\"	Date:   Tue Sep 6 15:16:25 2005 -0700
.\" FIXME. (Torvald) The glibc condvar implementation is currently being
.\"     revised (e.g., to not use an internal lock anymore).
.\"     It is probably more future-proof to remove this paragraph.
.\" [Torvald, do you have an update here?]
This operation was added to support some user-space use cases
where more than one futex must be handled at the same time.
The most notable example is the implementation of
.BR pthread_cond_signal (3),
which requires operations on two futexes,
the one used to implement the mutex and the one used in the implementation
of the wait queue associated with the condition variable.
.B FUTEX_WAKE_OP
allows such cases to be implemented without leading to
high rates of contention and context switching.
.IP
The
.B FUTEX_WAKE_OP
operation is equivalent to executing the following code atomically
and totally ordered with respect to other futex operations on
any of the two supplied futex words:
.IP
.in +4n
.EX
uint32_t oldval = *(uint32_t *) uaddr2;
*(uint32_t *) uaddr2 = oldval \fIop\fP \fIoparg\fP;
futex(uaddr, FUTEX_WAKE, val, 0, 0, 0);
if (oldval \fIcmp\fP \fIcmparg\fP)
    futex(uaddr2, FUTEX_WAKE, val2, 0, 0, 0);
.EE
.in
.IP
In other words,
.B FUTEX_WAKE_OP
does the following:
.RS
.IP \[bu] 3
saves the original value of the futex word at
.I uaddr2
and performs an operation to modify the value of the futex at
.IR uaddr2 ;
this is an atomic read-modify-write memory access (i.e., using atomic
machine instructions of the respective architecture)
.IP \[bu]
wakes up a maximum of
.I val
waiters on the futex for the futex word at
.IR uaddr ;
and
.IP \[bu]
dependent on the results of a test of the original value of the
futex word at
.IR uaddr2 ,
wakes up a maximum of
.I val2
waiters on the futex for the futex word at
.IR uaddr2 .
.RE
.IP
The operation and comparison that are to be performed are encoded
in the bits of the argument
.IR val3 .
Pictorially, the encoding is:
.IP
.in +4n
.EX
+---+---+-----------+-----------+
|op |cmp|   oparg   |  cmparg   |
+---+---+-----------+-----------+
  4   4       12          12    <== # of bits
.EE
.in
.IP
Expressed in code, the encoding is:
.IP
.in +4n
.EX
#define FUTEX_OP(op, oparg, cmp, cmparg) \e
                (((op & 0xf) << 28) | \e
                ((cmp & 0xf) << 24) | \e
                ((oparg & 0xfff) << 12) | \e
                (cmparg & 0xfff))
.EE
.in
.IP
In the above,
.I op
and
.I cmp
are each one of the codes listed below.
The
.I oparg
and
.I cmparg
components are literal numeric values, except as noted below.
.IP
The
.I op
component has one of the following values:
.IP
.in +4n
.EX
FUTEX_OP_SET        0  /* uaddr2 = oparg; */
FUTEX_OP_ADD        1  /* uaddr2 += oparg; */
FUTEX_OP_OR         2  /* uaddr2 |= oparg; */
FUTEX_OP_ANDN       3  /* uaddr2 &= \[ti]oparg; */
FUTEX_OP_XOR        4  /* uaddr2 \[ha]= oparg; */
.EE
.in
.IP
In addition, bitwise ORing the following value into
.I op
causes
.I (1\~<<\~oparg)
to be used as the operand:
.IP
.in +4n
.EX
FUTEX_OP_ARG_SHIFT  8  /* Use (1 << oparg) as operand */
.EE
.in
.IP
The
.I cmp
field is one of the following:
.IP
.in +4n
.EX
FUTEX_OP_CMP_EQ     0  /* if (oldval == cmparg) wake */
FUTEX_OP_CMP_NE     1  /* if (oldval != cmparg) wake */
FUTEX_OP_CMP_LT     2  /* if (oldval < cmparg) wake */
FUTEX_OP_CMP_LE     3  /* if (oldval <= cmparg) wake */
FUTEX_OP_CMP_GT     4  /* if (oldval > cmparg) wake */
FUTEX_OP_CMP_GE     5  /* if (oldval >= cmparg) wake */
.EE
.in
.IP
The return value of
.B FUTEX_WAKE_OP
is the sum of the number of waiters woken on the futex
.I uaddr
plus the number of waiters woken on the futex
.IR uaddr2 .
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)"
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
This operation is like
.B FUTEX_WAIT
except that
.I val3
is used to provide a 32-bit bit mask to the kernel.
This bit mask, in which at least one bit must be set,
is stored in the kernel-internal state of the waiter.
See the description of
.B FUTEX_WAKE_BITSET
for further details.
.IP
If
.I timeout
is not NULL, the structure it points to specifies
an absolute timeout for the wait operation.
If
.I timeout
is NULL, the operation can block indefinitely.
.IP
The
.I uaddr2
argument is ignored.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)"
.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
This operation is the same as
.B FUTEX_WAKE
except that the
.I val3
argument is used to provide a 32-bit bit mask to the kernel.
This bit mask, in which at least one bit must be set,
is used to select which waiters should be woken up.
The selection is done by a bitwise AND of the "wake" bit mask
(i.e., the value in
.IR val3 )
and the bit mask which is stored in the kernel-internal
state of the waiter (the "wait" bit mask that is set using
.BR FUTEX_WAIT_BITSET ).
All of the waiters for which the result of the AND is nonzero are woken up;
the remaining waiters are left sleeping.
.IP
The effect of
.B FUTEX_WAIT_BITSET
and
.B FUTEX_WAKE_BITSET
is to allow selective wake-ups among multiple waiters that are blocked
on the same futex.
However, note that, depending on the use case,
employing this bit-mask multiplexing feature on a
futex can be less efficient than simply using multiple futexes,
because employing bit-mask multiplexing requires the kernel
to check all waiters on a futex,
including those that are not interested in being woken up
(i.e., they do not have the relevant bit set in their "wait" bit mask).
.\" According to http://locklessinc.com/articles/futex_cheat_sheet/:
.\"
.\"    "The original reason for the addition of these extensions
.\"     was to improve the performance of pthread read-write locks
.\"     in glibc. However, the pthreads library no longer uses the
.\"     same locking algorithm, and these extensions are not used
.\"     without the bitset parameter being all ones.
.\"
.\" The page goes on to note that the FUTEX_WAIT_BITSET operation
.\" is nevertheless used (with a bit mask of all ones) in order to
.\" obtain the absolute timeout functionality that is useful
.\" for efficiently implementing Pthreads APIs (which use absolute
.\" timeouts); FUTEX_WAIT provides only relative timeouts.
.IP
The constant
.BR FUTEX_BITSET_MATCH_ANY ,
which corresponds to all 32 bits set in the bit mask, can be used as the
.I val3
argument for
.B FUTEX_WAIT_BITSET
and
.BR FUTEX_WAKE_BITSET .
Other than differences in the handling of the
.I timeout
argument, the
.B FUTEX_WAIT
operation is equivalent to
.B FUTEX_WAIT_BITSET
with
.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY ;
that is, allow a wake-up by any waker.
The
.B FUTEX_WAKE
operation is equivalent to
.B FUTEX_WAKE_BITSET
with
.I val3
specified as
.BR FUTEX_BITSET_MATCH_ANY ;
that is, wake up any waiter(s).
.IP
The
.I uaddr2
and
.I timeout
arguments are ignored.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.SS Priority-inheritance futexes
Linux supports priority-inheritance (PI) futexes in order to handle
priority-inversion problems that can be encountered with
normal futex locks.
Priority inversion is the problem that occurs when a high-priority
task is blocked waiting to acquire a lock held by a low-priority task,
while tasks at an intermediate priority continuously preempt
the low-priority task from the CPU.
Consequently, the low-priority task makes no progress toward
releasing the lock, and the high-priority task remains blocked.
.PP
Priority inheritance is a mechanism for dealing with
the priority-inversion problem.
With this mechanism, when a high-priority task becomes blocked
by a lock held by a low-priority task,
the priority of the low-priority task is temporarily raised
to that of the high-priority task,
so that it is not preempted by any intermediate level tasks,
and can thus make progress toward releasing the lock.
To be effective, priority inheritance must be transitive,
meaning that if a high-priority task blocks on a lock
held by a lower-priority task that is itself blocked by a lock
held by another intermediate-priority task
(and so on, for chains of arbitrary length),
then both of those tasks
(or more generally, all of the tasks in a lock chain)
have their priorities raised to be the same as the high-priority task.
.PP
From a user-space perspective,
what makes a futex PI-aware is a policy agreement (described below)
between user space and the kernel about the value of the futex word,
coupled with the use of the PI-futex operations described below.
(Unlike the other futex operations described above,
the PI-futex operations are designed
for the implementation of very specific IPC mechanisms.)
.\"
.\" Quoting Darren Hart:
.\"     These opcodes paired with the PI futex value policy (described below)
.\"     defines a "futex" as PI aware. These were created very specifically
.\"     in support of PI pthread_mutexes, so it makes a lot more sense to
.\"     talk about a PI aware pthread_mutex, than a PI aware futex, since
.\"     there is a lot of policy and scaffolding that has to be built up
.\"     around it to use it properly (this is what a PI pthread_mutex is).
.PP
.\"       mtk: The following text is drawn from the Hart/Guniguntala paper
.\"       (listed in SEE ALSO), but I have reworded some pieces
.\"       significantly.
.\"
The PI-futex operations described below differ from the other
futex operations in that they impose policy on the use of the value of the
futex word:
.IP \[bu] 3
If the lock is not acquired, the futex word's value shall be 0.
.IP \[bu]
If the lock is acquired, the futex word's value shall
be the thread ID (TID;
see
.BR gettid (2))
of the owning thread.
.IP \[bu]
If the lock is owned and there are threads contending for the lock,
then the
.B FUTEX_WAITERS
bit shall be set in the futex word's value; in other words, this value is:
.IP
.in +4n
.EX
FUTEX_WAITERS | TID
.EE
.in
.IP
(Note that is invalid for a PI futex word to have no owner and
.B FUTEX_WAITERS
set.)
.PP
With this policy in place,
a user-space application can acquire an unacquired
lock or release a lock using atomic instructions executed in user mode
(e.g., a compare-and-swap operation such as
.I cmpxchg
on the x86 architecture).
Acquiring a lock simply consists of using compare-and-swap to atomically
set the futex word's value to the caller's TID if its previous value was 0.
Releasing a lock requires using compare-and-swap to set the futex word's
value to 0 if the previous value was the expected TID.
.PP
If a futex is already acquired (i.e., has a nonzero value),
waiters must employ the
.B FUTEX_LOCK_PI
or
.B FUTEX_LOCK_PI2
operations to acquire the lock.
If other threads are waiting for the lock, then the
.B FUTEX_WAITERS
bit is set in the futex value;
in this case, the lock owner must employ the
.B FUTEX_UNLOCK_PI
operation to release the lock.
.PP
In the cases where callers are forced into the kernel
(i.e., required to perform a
.BR futex ()
call),
they then deal directly with a so-called RT-mutex,
a kernel locking mechanism which implements the required
priority-inheritance semantics.
After the RT-mutex is acquired, the futex value is updated accordingly,
before the calling thread returns to user space.
.PP
It is important to note
.\" tglx (July 2015):
.\"     If there are multiple waiters on a pi futex then a wake pi operation
.\"     will wake the first waiter and hand over the lock to this waiter. This
.\"     includes handing over the rtmutex which represents the futex in the
.\"     kernel. The strict requirement is that the futex owner and the rtmutex
.\"     owner must be the same, except for the update period which is
.\"     serialized by the futex internal locking. That means the kernel must
.\"     update the user-space value prior to returning to user space
that the kernel will update the futex word's value prior
to returning to user space.
(This prevents the possibility of the futex word's value ending
up in an invalid state, such as having an owner but the value being 0,
or having waiters but not having the
.B FUTEX_WAITERS
bit set.)
.PP
If a futex has an associated RT-mutex in the kernel
(i.e., there are blocked waiters)
and the owner of the futex/RT-mutex dies unexpectedly,
then the kernel cleans up the RT-mutex and hands it over to the next waiter.
This in turn requires that the user-space value is updated accordingly.
To indicate that this is required, the kernel sets the
.B FUTEX_OWNER_DIED
bit in the futex word along with the thread ID of the new owner.
User space can detect this situation via the presence of the
.B FUTEX_OWNER_DIED
bit and is then responsible for cleaning up the stale state left over by
the dead owner.
.\" tglx (July 2015):
.\"     The FUTEX_OWNER_DIED bit can also be set on uncontended futexes, where
.\"     the kernel has no state associated. This happens via the robust futex
.\"     mechanism. In that case the futex value will be set to
.\"     FUTEX_OWNER_DIED. The robust futex mechanism is also available for non
.\"     PI futexes.
.PP
PI futexes are operated on by specifying one of the values listed below in
.IR futex_op .
Note that the PI futex operations must be used as paired operations
and are subject to some additional requirements:
.IP \[bu] 3
.BR FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
and
.B FUTEX_TRYLOCK_PI
pair with
.BR FUTEX_UNLOCK_PI .
.B FUTEX_UNLOCK_PI
must be called only on a futex owned by the calling thread,
as defined by the value policy, otherwise the error
.B EPERM
results.
.IP \[bu]
.B FUTEX_WAIT_REQUEUE_PI
pairs with
.BR FUTEX_CMP_REQUEUE_PI .
This must be performed from a non-PI futex to a distinct PI futex
(or the error
.B EINVAL
results).
Additionally,
.I val
(the number of waiters to be woken) must be 1
(or the error
.B EINVAL
results).
.PP
The PI futex operations are as follows:
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_LOCK_PI " (since Linux 2.6.18)"
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
This operation is used after an attempt to acquire
the lock via an atomic user-mode instruction failed
because the futex word has a nonzero value\[em]specifically,
because it contained the (PID-namespace-specific) TID of the lock owner.
.IP
The operation checks the value of the futex word at the address
.IR uaddr .
If the value is 0, then the kernel tries to atomically set
the futex value to the caller's TID.
If the futex word's value is nonzero,
the kernel atomically sets the
.B FUTEX_WAITERS
bit, which signals the futex owner that it cannot unlock the futex in
user space atomically by setting the futex value to 0.
.\" tglx (July 2015):
.\"     The operation here is similar to the FUTEX_WAIT logic. When the user
.\"     space atomic acquire does not succeed because the futex value was non
.\"     zero, then the waiter goes into the kernel, takes the kernel internal
.\"     lock and retries the acquisition under the lock. If the acquisition
.\"     does not succeed either, then it sets the FUTEX_WAITERS bit, to signal
.\"     the lock owner that it needs to go into the kernel. Here is the pseudo
.\"     code:
.\"
.\"     	lock(kernel_lock);
.\"     retry:
.\"
.\"     	/*
.\"     	 * Owner might have unlocked in user space before we
.\"     	 * were able to set the waiter bit.
.\"              */
.\"             if (atomic_acquire(futex) == SUCCESS) {
.\"     	   unlock(kernel_lock());
.\"     	   return 0;
.\"     	}
.\"
.\"     	/*
.\"     	 * Owner might have unlocked after the above atomic_acquire()
.\"     	 * attempt.
.\"     	 */
.\"     	if (atomic_set_waiters_bit(futex) != SUCCESS)
.\"     	   goto retry;
.\"
.\"     	queue_waiter();
.\"     	unlock(kernel_lock);
.\"     	block();
.\"
After that, the kernel:
.RS
.IP (1) 5
Tries to find the thread which is associated with the owner TID.
.IP (2)
Creates or reuses kernel state on behalf of the owner.
(If this is the first waiter, there is no kernel state for this
futex, so kernel state is created by locking the RT-mutex
and the futex owner is made the owner of the RT-mutex.
If there are existing waiters, then the existing state is reused.)
.IP (3)
Attaches the waiter to the futex
(i.e., the waiter is enqueued on the RT-mutex waiter list).
.RE
.IP
If more than one waiter exists,
the enqueueing of the waiter is in descending priority order.
(For information on priority ordering, see the discussion of the
.BR SCHED_DEADLINE ,
.BR SCHED_FIFO ,
and
.B SCHED_RR
scheduling policies in
.BR sched (7).)
The owner inherits either the waiter's CPU bandwidth
(if the waiter is scheduled under the
.B SCHED_DEADLINE
policy) or the waiter's priority (if the waiter is scheduled under the
.B SCHED_RR
or
.B SCHED_FIFO
policy).
.\" August 2015:
.\"     mtk: If the realm is restricted purely to SCHED_OTHER (SCHED_NORMAL)
.\"          processes, does the nice value come into play also?
.\"
.\"     tglx: No. SCHED_OTHER/NORMAL tasks are handled in FIFO order
This inheritance follows the lock chain in the case of nested locking
.\" (i.e., task 1 blocks on lock A, held by task 2,
.\" while task 2 blocks on lock B, held by task 3)
and performs deadlock detection.
.IP
The
.I timeout
argument provides a timeout for the lock attempt.
If
.I timeout
is not NULL, the structure it points to specifies
an absolute timeout, measured against the
.B CLOCK_REALTIME
clock.
.\" 2016-07-07 response from Thomas Gleixner on LKML:
.\" From: Thomas Gleixner <tglx@linutronix.de>
.\" Date: 6 July 2016 at 20:57
.\" Subject: Re: futex: Allow FUTEX_CLOCK_REALTIME with FUTEX_WAIT op
.\"
.\" On Thu, 23 Jun 2016, Michael Kerrisk (man-pages) wrote:
.\" > On 06/23/2016 08:28 PM, Darren Hart wrote:
.\" > > And as a follow-on, what is the reason for FUTEX_LOCK_PI only using
.\" > > CLOCK_REALTIME? It seems reasonable to me that a user may want to wait a
.\" > > specific amount of time, regardless of wall time.
.\" >
.\" > Yes, that's another weird inconsistency.
.\"
.\" The reason is that phtread_mutex_timedlock() uses absolute timeouts based on
.\" CLOCK_REALTIME. glibc folks asked to make that the default behaviour back
.\" then when we added LOCK_PI.
If
.I timeout
is NULL, the operation will block indefinitely.
.IP
The
.IR uaddr2 ,
.IR val ,
and
.I val3
arguments are ignored.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_LOCK_PI2 " (since Linux 5.14)"
.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae
This operation is the same as
.BR FUTEX_LOCK_PI ,
except that the clock against which
.I timeout
is measured is selectable.
By default, the (absolute) timeout specified in
.I timeout
is measured against the
.B CLOCK_MONOTONIC
clock, but if the
.B FUTEX_CLOCK_REALTIME
flag is specified in
.IR futex_op ,
then the timeout is measured against the
.B CLOCK_REALTIME
clock.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)"
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
This operation tries to acquire the lock at
.IR uaddr .
It is invoked when a user-space atomic acquire did not
succeed because the futex word was not 0.
.IP
Because the kernel has access to more state information than user space,
acquisition of the lock might succeed if performed by the
kernel in cases where the futex word
(i.e., the state information accessible to use-space) contains stale state
.RB ( FUTEX_WAITERS
and/or
.BR FUTEX_OWNER_DIED ).
This can happen when the owner of the futex died.
User space cannot handle this condition in a race-free manner,
but the kernel can fix this up and acquire the futex.
.\" Paraphrasing a f2f conversation with Thomas Gleixner about the
.\" above point (Aug 2015): ###
.\"	There is a rare possibility of a race condition involving an
.\"	uncontended futex with no owner, but with waiters.  The
.\"	kernel-user-space contract is that if a futex is nonzero, you must
.\"	go into kernel.  The futex was owned by a task, and that task dies
.\"	but there are no waiters, so the futex value is non zero.
.\"	Therefore, the next locker has to go into the kernel,
.\"	so that the kernel has a chance to clean up. (CMXCH on zero
.\"	in user space would fail, so kernel has to clean up.)
.\" Darren Hart (Oct 2015):
.\"     The trylock in the kernel has more state, so it can independently
.\"     verify the flags that user space must trust implicitly.
.IP
The
.IR uaddr2 ,
.IR val ,
.IR timeout ,
and
.I val3
arguments are ignored.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_UNLOCK_PI " (since Linux 2.6.18)"
.\" commit c87e2837be82df479a6bae9f155c43516d2feebc
This operation wakes the top priority waiter that is waiting in
.B FUTEX_LOCK_PI
or
.B FUTEX_LOCK_PI2
on the futex address provided by the
.I uaddr
argument.
.IP
This is called when the user-space value at
.I uaddr
cannot be changed atomically from a TID (of the owner) to 0.
.IP
The
.IR uaddr2 ,
.IR val ,
.IR timeout ,
and
.I val3
arguments are ignored.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_CMP_REQUEUE_PI " (since Linux 2.6.31)"
.\" commit 52400ba946759af28442dee6265c5c0180ac7122
This operation is a PI-aware variant of
.BR FUTEX_CMP_REQUEUE .
It requeues waiters that are blocked via
.B FUTEX_WAIT_REQUEUE_PI
on
.I uaddr
from a non-PI source futex
.RI ( uaddr )
to a PI target futex
.RI ( uaddr2 ).
.IP
As with
.BR FUTEX_CMP_REQUEUE ,
this operation wakes up a maximum of
.I val
waiters that are waiting on the futex at
.IR uaddr .
However, for
.BR FUTEX_CMP_REQUEUE_PI ,
.I val
is required to be 1
(since the main point is to avoid a thundering herd).
The remaining waiters are removed from the wait queue of the source futex at
.I uaddr
and added to the wait queue of the target futex at
.IR uaddr2 .
.IP
The
.I val2
.\" val2 is the cap on the number of requeued waiters.
.\" In the glibc pthread_cond_broadcast() implementation, this argument
.\" is specified as INT_MAX, and for pthread_cond_signal() it is 0.
and
.I val3
arguments serve the same purposes as for
.BR FUTEX_CMP_REQUEUE .
.\"
.\"       The page at http://locklessinc.com/articles/futex_cheat_sheet/
.\"       notes that "priority-inheritance Futex to priority-inheritance
.\"       Futex requeues are currently unsupported". However, probably
.\"       the page does not need to say nothing about this, since
.\"       Thomas Gleixner commented (July 2015): "they never will be
.\"       supported because they make no sense at all"
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.TP
.BR FUTEX_WAIT_REQUEUE_PI " (since Linux 2.6.31)"
.\" commit 52400ba946759af28442dee6265c5c0180ac7122
.\"
Wait on a non-PI futex at
.I uaddr
and potentially be requeued (via a
.B FUTEX_CMP_REQUEUE_PI
operation in another task) onto a PI futex at
.IR uaddr2 .
The wait operation on
.I uaddr
is the same as for
.BR FUTEX_WAIT .
.IP
The waiter can be removed from the wait on
.I uaddr
without requeueing on
.I uaddr2
via a
.B FUTEX_WAKE
operation in another task.
In this case, the
.B FUTEX_WAIT_REQUEUE_PI
operation fails with the error
.BR EAGAIN .
.IP
If
.I timeout
is not NULL, the structure it points to specifies
an absolute timeout for the wait operation.
If
.I timeout
is NULL, the operation can block indefinitely.
.IP
The
.I val3
argument is ignored.
.IP
The
.B FUTEX_WAIT_REQUEUE_PI
and
.B FUTEX_CMP_REQUEUE_PI
were added to support a fairly specific use case:
support for priority-inheritance-aware POSIX threads condition variables.
The idea is that these operations should always be paired,
in order to ensure that user space and the kernel remain in sync.
Thus, in the
.B FUTEX_WAIT_REQUEUE_PI
operation, the user-space application pre-specifies the target
of the requeue that takes place in the
.B FUTEX_CMP_REQUEUE_PI
operation.
.\"
.\" Darren Hart notes that a patch to allow glibc to fully support
.\" PI-aware pthreads condition variables has not yet been accepted into
.\" glibc. The story is complex, and can be found at
.\" https://sourceware.org/bugzilla/show_bug.cgi?id=11588
.\" Darren notes that in the meantime, the patch is shipped with various
.\" PREEMPT_RT-enabled Linux systems.
.\"
.\" Related to the preceding, Darren proposed that somewhere, man-pages
.\" should document the following point:
.\"
.\"     While the Linux kernel, since Linux 2.6.31, supports requeueing of
.\"     priority-inheritance (PI) aware mutexes via the
.\"     FUTEX_WAIT_REQUEUE_PI and FUTEX_CMP_REQUEUE_PI futex operations,
.\"     the glibc implementation does not yet take full advantage of this.
.\"     Specifically, the condvar internal data lock remains a non-PI aware
.\"     mutex, regardless of the type of the pthread_mutex associated with
.\"     the condvar. This can lead to an unbounded priority inversion on
.\"     the internal data lock even when associating a PI aware
.\"     pthread_mutex with a condvar during a pthread_cond*_wait
.\"     operation. For this reason, it is not recommended to rely on
.\"     priority inheritance when using pthread condition variables.
.\"
.\" The problem is that the obvious location for this text is
.\" the pthread_cond*wait(3) man page. However, such a man page
.\" does not currently exist.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.SH RETURN VALUE
In the event of an error (and assuming that
.BR futex ()
was invoked via
.BR syscall (2)),
all operations return \-1 and set
.I errno
to indicate the error.
.PP
The return value on success depends on the operation,
as described in the following list:
.TP
.B FUTEX_WAIT
Returns 0 if the caller was woken up.
Note that a wake-up can also be caused by common futex usage patterns
in unrelated code that happened to have previously used the futex word's
memory location (e.g., typical futex-based implementations of
Pthreads mutexes can cause this under some conditions).
Therefore, callers should always conservatively assume that a return
value of 0 can mean a spurious wake-up, and use the futex word's value
(i.e., the user-space synchronization scheme)
to decide whether to continue to block or not.
.TP
.B FUTEX_WAKE
Returns the number of waiters that were woken up.
.TP
.B FUTEX_FD
Returns the new file descriptor associated with the futex.
.TP
.B FUTEX_REQUEUE
Returns the number of waiters that were woken up.
.TP
.B FUTEX_CMP_REQUEUE
Returns the total number of waiters that were woken up or
requeued to the futex for the futex word at
.IR uaddr2 .
If this value is greater than
.IR val ,
then the difference is the number of waiters requeued to the futex for the
futex word at
.IR uaddr2 .
.TP
.B FUTEX_WAKE_OP
Returns the total number of waiters that were woken up.
This is the sum of the woken waiters on the two futexes for
the futex words at
.I uaddr
and
.IR uaddr2 .
.TP
.B FUTEX_WAIT_BITSET
Returns 0 if the caller was woken up.
See
.B FUTEX_WAIT
for how to interpret this correctly in practice.
.TP
.B FUTEX_WAKE_BITSET
Returns the number of waiters that were woken up.
.TP
.B FUTEX_LOCK_PI
Returns 0 if the futex was successfully locked.
.TP
.B FUTEX_LOCK_PI2
Returns 0 if the futex was successfully locked.
.TP
.B FUTEX_TRYLOCK_PI
Returns 0 if the futex was successfully locked.
.TP
.B FUTEX_UNLOCK_PI
Returns 0 if the futex was successfully unlocked.
.TP
.B FUTEX_CMP_REQUEUE_PI
Returns the total number of waiters that were woken up or
requeued to the futex for the futex word at
.IR uaddr2 .
If this value is greater than
.IR val ,
then difference is the number of waiters requeued to the futex for
the futex word at
.IR uaddr2 .
.TP
.B FUTEX_WAIT_REQUEUE_PI
Returns 0 if the caller was successfully requeued to the futex for
the futex word at
.IR uaddr2 .
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.SH ERRORS
.TP
.B EACCES
No read access to the memory of a futex word.
.TP
.B EAGAIN
.RB ( FUTEX_WAIT ,
.BR FUTEX_WAIT_BITSET ,
.BR FUTEX_WAIT_REQUEUE_PI )
The value pointed to by
.I uaddr
was not equal to the expected value
.I val
at the time of the call.
.IP
.BR Note :
on Linux, the symbolic names
.B EAGAIN
and
.B EWOULDBLOCK
(both of which appear in different parts of the kernel futex code)
have the same value.
.TP
.B EAGAIN
.RB ( FUTEX_CMP_REQUEUE ,
.BR FUTEX_CMP_REQUEUE_PI )
The value pointed to by
.I uaddr
is not equal to the expected value
.IR val3 .
.TP
.B EAGAIN
.RB ( FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
.BR FUTEX_TRYLOCK_PI ,
.BR FUTEX_CMP_REQUEUE_PI )
The futex owner thread ID of
.I uaddr
(for
.BR FUTEX_CMP_REQUEUE_PI :
.IR uaddr2 )
is about to exit,
but has not yet handled the internal state cleanup.
Try again.
.TP
.B EDEADLK
.RB ( FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
.BR FUTEX_TRYLOCK_PI ,
.BR FUTEX_CMP_REQUEUE_PI )
The futex word at
.I uaddr
is already locked by the caller.
.TP
.B EDEADLK
.\" FIXME . I see that kernel/locking/rtmutex.c uses EDEADLK in some
.\"       places, and EDEADLOCK in others. On almost all architectures
.\"       these constants are synonymous. Is there a reason that both
.\"       names are used?
.\"
.\"       tglx (July 2015): "No. We should probably fix that."
.\"
.RB ( FUTEX_CMP_REQUEUE_PI )
While requeueing a waiter to the PI futex for the futex word at
.IR uaddr2 ,
the kernel detected a deadlock.
.TP
.B EFAULT
A required pointer argument (i.e.,
.IR uaddr ,
.IR uaddr2 ,
or
.IR timeout )
did not point to a valid user-space address.
.TP
.B EINTR
A
.B FUTEX_WAIT
or
.B FUTEX_WAIT_BITSET
operation was interrupted by a signal (see
.BR signal (7)).
Before Linux 2.6.22, this error could also be returned for
a spurious wakeup; since Linux 2.6.22, this no longer happens.
.TP
.B EINVAL
The operation in
.I futex_op
is one of those that employs a timeout, but the supplied
.I timeout
argument was invalid
.RI ( tv_sec
was less than zero, or
.I tv_nsec
was not less than 1,000,000,000).
.TP
.B EINVAL
The operation specified in
.I futex_op
employs one or both of the pointers
.I uaddr
and
.IR uaddr2 ,
but one of these does not point to a valid object\[em]that is,
the address is not four-byte-aligned.
.TP
.B EINVAL
.RB ( FUTEX_WAIT_BITSET ,
.BR FUTEX_WAKE_BITSET )
The bit mask supplied in
.I val3
is zero.
.TP
.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
.I uaddr
equals
.I uaddr2
(i.e., an attempt was made to requeue to the same futex).
.TP
.B EINVAL
.RB ( FUTEX_FD )
The signal number supplied in
.I val
is invalid.
.TP
.B EINVAL
.RB ( FUTEX_WAKE ,
.BR FUTEX_WAKE_OP ,
.BR FUTEX_WAKE_BITSET ,
.BR FUTEX_REQUEUE ,
.BR FUTEX_CMP_REQUEUE )
The kernel detected an inconsistency between the user-space state at
.I uaddr
and the kernel state\[em]that is, it detected a waiter which waits in
.B FUTEX_LOCK_PI
or
.B FUTEX_LOCK_PI2
on
.IR uaddr .
.TP
.B EINVAL
.RB ( FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
.BR FUTEX_TRYLOCK_PI ,
.BR FUTEX_UNLOCK_PI )
The kernel detected an inconsistency between the user-space state at
.I uaddr
and the kernel state.
This indicates either state corruption
or that the kernel found a waiter on
.I uaddr
which is waiting via
.B FUTEX_WAIT
or
.BR FUTEX_WAIT_BITSET .
.TP
.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
The kernel detected an inconsistency between the user-space state at
.I uaddr2
and the kernel state;
.\" From a conversation with Thomas Gleixner (Aug 2015): ###
.\"	The kernel sees: I have non PI state for a futex you tried to
.\"     tell me was PI
that is, the kernel detected a waiter which waits via
.B FUTEX_WAIT
or
.B FUTEX_WAIT_BITSET
on
.IR uaddr2 .
.TP
.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
The kernel detected an inconsistency between the user-space state at
.I uaddr
and the kernel state;
that is, the kernel detected a waiter which waits via
.B FUTEX_WAIT
or
.B FUTEX_WAIT_BITSET
on
.IR uaddr .
.TP
.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
The kernel detected an inconsistency between the user-space state at
.I uaddr
and the kernel state;
that is, the kernel detected a waiter which waits on
.I uaddr
via
.B FUTEX_LOCK_PI
or
.B FUTEX_LOCK_PI2
(instead of
.BR FUTEX_WAIT_REQUEUE_PI ).
.TP
.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
.\" This deals with the case:
.\"     wait_requeue_pi(A, B);
.\"     requeue_pi(A, C);
An attempt was made to requeue a waiter to a futex other than that
specified by the matching
.B FUTEX_WAIT_REQUEUE_PI
call for that waiter.
.TP
.B EINVAL
.RB ( FUTEX_CMP_REQUEUE_PI )
The
.I val
argument is not 1.
.TP
.B EINVAL
Invalid argument.
.TP
.B ENFILE
.RB ( FUTEX_FD )
The system-wide limit on the total number of open files has been reached.
.TP
.B ENOMEM
.RB ( FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
.BR FUTEX_TRYLOCK_PI ,
.BR FUTEX_CMP_REQUEUE_PI )
The kernel could not allocate memory to hold state information.
.TP
.B ENOSYS
Invalid operation specified in
.IR futex_op .
.TP
.B ENOSYS
The
.B FUTEX_CLOCK_REALTIME
option was specified in
.IR futex_op ,
but the accompanying operation was neither
.BR FUTEX_WAIT ,
.BR FUTEX_WAIT_BITSET ,
.BR FUTEX_WAIT_REQUEUE_PI ,
nor
.BR FUTEX_LOCK_PI2 .
.TP
.B ENOSYS
.RB ( FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
.BR FUTEX_TRYLOCK_PI ,
.BR FUTEX_UNLOCK_PI ,
.BR FUTEX_CMP_REQUEUE_PI ,
.BR FUTEX_WAIT_REQUEUE_PI )
A run-time check determined that the operation is not available.
The PI-futex operations are not implemented on all architectures and
are not supported on some CPU variants.
.TP
.B EPERM
.RB ( FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
.BR FUTEX_TRYLOCK_PI ,
.BR FUTEX_CMP_REQUEUE_PI )
The caller is not allowed to attach itself to the futex at
.I uaddr
(for
.BR FUTEX_CMP_REQUEUE_PI :
the futex at
.IR uaddr2 ).
(This may be caused by a state corruption in user space.)
.TP
.B EPERM
.RB ( FUTEX_UNLOCK_PI )
The caller does not own the lock represented by the futex word.
.TP
.B ESRCH
.RB ( FUTEX_LOCK_PI ,
.BR FUTEX_LOCK_PI2 ,
.BR FUTEX_TRYLOCK_PI ,
.BR FUTEX_CMP_REQUEUE_PI )
The thread ID in the futex word at
.I uaddr
does not exist.
.TP
.B ESRCH
.RB ( FUTEX_CMP_REQUEUE_PI )
The thread ID in the futex word at
.I uaddr2
does not exist.
.TP
.B ETIMEDOUT
The operation in
.I futex_op
employed the timeout specified in
.IR timeout ,
and the timeout expired before the operation completed.
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.6.0.
.PP
Initial futex support was merged in Linux 2.5.7 but with different
semantics from what was described above.
A four-argument system call with the semantics
described in this page was introduced in Linux 2.5.40.
A fifth argument was added in Linux 2.5.70,
and a sixth argument was added in Linux 2.6.7.
.SH EXAMPLES
The program below demonstrates use of futexes in a program where a parent
process and a child process use a pair of futexes located inside a
shared anonymous mapping to synchronize access to a shared resource:
the terminal.
The two processes each write
.I nloops
(a command-line argument that defaults to 5 if omitted)
messages to the terminal and employ a synchronization protocol
that ensures that they alternate in writing messages.
Upon running this program we see output such as the following:
.PP
.in +4n
.EX
$ \fB./futex_demo\fP
Parent (18534) 0
Child  (18535) 0
Parent (18534) 1
Child  (18535) 1
Parent (18534) 2
Child  (18535) 2
Parent (18534) 3
Child  (18535) 3
Parent (18534) 4
Child  (18535) 4
.EE
.in
.SS Program source
\&
.\" SRC BEGIN (futex.c)
.EX
/* futex_demo.c
\&
   Usage: futex_demo [nloops]
                    (Default: 5)
\&
   Demonstrate the use of futexes in a program where parent and child
   use a pair of futexes located inside a shared anonymous mapping to
   synchronize access to a shared resource: the terminal. The two
   processes each write \[aq]num\-loops\[aq] messages to the terminal and employ
   a synchronization protocol that ensures that they alternate in
   writing messages.
*/
#define _GNU_SOURCE
#include <err.h>
#include <errno.h>
#include <linux/futex.h>
#include <stdatomic.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <sys/syscall.h>
#include <sys/time.h>
#include <sys/wait.h>
#include <unistd.h>
\&
static uint32_t *futex1, *futex2, *iaddr;
\&
static int
futex(uint32_t *uaddr, int futex_op, uint32_t val,
      const struct timespec *timeout, uint32_t *uaddr2, uint32_t val3)
{
    return syscall(SYS_futex, uaddr, futex_op, val,
                   timeout, uaddr2, val3);
}
\&
/* Acquire the futex pointed to by \[aq]futexp\[aq]: wait for its value to
   become 1, and then set the value to 0. */
\&
static void
fwait(uint32_t *futexp)
{
    long            s;
    const uint32_t  one = 1;
\&
    /* atomic_compare_exchange_strong(ptr, oldval, newval)
       atomically performs the equivalent of:
\&
           if (*ptr == *oldval)
               *ptr = newval;
\&
       It returns true if the test yielded true and *ptr was updated. */
\&
    while (1) {
\&
        /* Is the futex available? */
        if (atomic_compare_exchange_strong(futexp, &one, 0))
            break;      /* Yes */
\&
        /* Futex is not available; wait. */
\&
        s = futex(futexp, FUTEX_WAIT, 0, NULL, NULL, 0);
        if (s == \-1 && errno != EAGAIN)
            err(EXIT_FAILURE, "futex\-FUTEX_WAIT");
    }
}
\&
/* Release the futex pointed to by \[aq]futexp\[aq]: if the futex currently
   has the value 0, set its value to 1 and then wake any futex waiters,
   so that if the peer is blocked in fwait(), it can proceed. */
\&
static void
fpost(uint32_t *futexp)
{
    long            s;
    const uint32_t  zero = 0;
\&
    /* atomic_compare_exchange_strong() was described
       in comments above. */
\&
    if (atomic_compare_exchange_strong(futexp, &zero, 1)) {
        s = futex(futexp, FUTEX_WAKE, 1, NULL, NULL, 0);
        if (s  == \-1)
            err(EXIT_FAILURE, "futex\-FUTEX_WAKE");
    }
}
\&
int
main(int argc, char *argv[])
{
    pid_t         childPid;
    unsigned int  nloops;
\&
    setbuf(stdout, NULL);
\&
    nloops = (argc > 1) ? atoi(argv[1]) : 5;
\&
    /* Create a shared anonymous mapping that will hold the futexes.
       Since the futexes are being shared between processes, we
       subsequently use the "shared" futex operations (i.e., not the
       ones suffixed "_PRIVATE"). */
\&
    iaddr = mmap(NULL, sizeof(*iaddr) * 2, PROT_READ | PROT_WRITE,
                 MAP_ANONYMOUS | MAP_SHARED, \-1, 0);
    if (iaddr == MAP_FAILED)
        err(EXIT_FAILURE, "mmap");
\&
    futex1 = &iaddr[0];
    futex2 = &iaddr[1];
\&
    *futex1 = 0;        /* State: unavailable */
    *futex2 = 1;        /* State: available */
\&
    /* Create a child process that inherits the shared anonymous
       mapping. */
\&
    childPid = fork();
    if (childPid == \-1)
        err(EXIT_FAILURE, "fork");
\&
    if (childPid == 0) {        /* Child */
        for (unsigned int j = 0; j < nloops; j++) {
            fwait(futex1);
            printf("Child  (%jd) %u\en", (intmax_t) getpid(), j);
            fpost(futex2);
        }
\&
        exit(EXIT_SUCCESS);
    }
\&
    /* Parent falls through to here. */
\&
    for (unsigned int j = 0; j < nloops; j++) {
        fwait(futex2);
        printf("Parent (%jd) %u\en", (intmax_t) getpid(), j);
        fpost(futex1);
    }
\&
    wait(NULL);
\&
    exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH SEE ALSO
.ad l
.BR get_robust_list (2),
.BR restart_syscall (2),
.BR pthread_mutexattr_getprotocol (3),
.BR futex (7),
.BR sched (7)
.PP
The following kernel source files:
.IP \[bu] 3
.I Documentation/pi\-futex.txt
.IP \[bu]
.I Documentation/futex\-requeue\-pi.txt
.IP \[bu]
.I Documentation/locking/rt\-mutex.txt
.IP \[bu]
.I Documentation/locking/rt\-mutex\-design.txt
.IP \[bu]
.I Documentation/robust\-futex\-ABI.txt
.PP
Franke, H., Russell, R., and Kirwood, M., 2002.
\fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
(from proceedings of the Ottawa Linux Symposium 2002),
.br
.UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf
.UE
.PP
Hart, D., 2009. \fIA futex overview and update\fP,
.UR http://lwn.net/Articles/360699/
.UE
.PP
Hart, D.\& and Guniguntala, D., 2009.
\fIRequeue-PI: Making glibc Condvars PI-Aware\fP
(from proceedings of the 2009 Real-Time Linux Workshop),
.UR http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf
.UE
.PP
Drepper, U., 2011. \fIFutexes Are Tricky\fP,
.UR http://www.akkadia.org/drepper/futex.pdf
.UE
.PP
Futex example library, futex\-*.tar.bz2 at
.br
.UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
.UE
.\"
.\" FIXME(Torvald) We should probably refer to the glibc code here, in
.\" particular the glibc-internal futex wrapper functions that are
.\" WIP, and the generic pthread_mutex_t and perhaps condvar
.\" implementations.