]>
Commit | Line | Data |
---|---|---|
c13182ef | 1 | .\" This manpage has been automatically generated by docbook2man |
fea681da | 2 | .\" from a DocBook document. This tool can be found at: |
c13182ef MK |
3 | .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> |
4 | .\" Please send any bug reports, improvements, comments, patches, | |
fea681da | 5 | .\" etc. to Steve Cheng <steve@ggi-project.org>. |
2297bf0e MK |
6 | .\" |
7 | .\" %%%LICENSE_START(MIT) | |
8 | .\" This page is made available under the MIT license. | |
8ff7380d | 9 | .\" %%%LICENSE_END |
2297bf0e | 10 | .\" |
29b41e74 | 11 | .TH FUTEX 7 2015-12-28 "Linux" "Linux Programmer's Manual" |
fea681da | 12 | .SH NAME |
f68512e9 | 13 | futex \- fast user-space locking |
fea681da MK |
14 | .SH SYNOPSIS |
15 | .nf | |
62218dc0 | 16 | .B #include <linux/futex.h> |
fea681da MK |
17 | .fi |
18 | .SH DESCRIPTION | |
19 | .PP | |
7fac88a9 MK |
20 | The Linux kernel provides futexes ("Fast user-space mutexes") |
21 | as a building block for fast user-space | |
c13182ef | 22 | locking and semaphores. |
61bba8b4 | 23 | Futexes are very basic and lend themselves well for building higher-level |
a543ff10 MK |
24 | locking abstractions such as |
25 | mutexes, condition variables, read-write locks, barriers, and semaphores. | |
fea681da | 26 | .PP |
61bba8b4 | 27 | Most programmers will in fact not be using futexes directly but will |
c13182ef | 28 | instead rely on system libraries built on them, |
b96e00fe HS |
29 | such as the Native POSIX Thread Library (NPTL) (see |
30 | .BR pthreads (7)). | |
fea681da | 31 | .PP |
c13182ef | 32 | A futex is identified by a piece of memory which can be |
66d1619c | 33 | shared between processes or threads. |
61bba8b4 | 34 | In these different processes, the futex need not have identical addresses. |
c13182ef MK |
35 | In its bare form, a futex has semaphore semantics; |
36 | it is a counter that can be incremented and decremented atomically; | |
b29c9ff2 | 37 | processes can wait for the value to become positive. |
fea681da | 38 | .PP |
61bba8b4 | 39 | Futex operation occurs entirely in user space for the noncontended case. |
33a0ccb2 | 40 | The kernel is involved only to arbitrate the contended case. |
24b74457 | 41 | As any sane design will strive for noncontention, |
d9bfdb9c | 42 | futexes are also optimized for this situation. |
fea681da | 43 | .PP |
c13182ef | 44 | In its bare form, a futex is an aligned integer which is |
33a0ccb2 | 45 | touched only by atomic assembler instructions. |
dc146cb4 | 46 | This integer is four bytes long on all platforms. |
c13182ef | 47 | Processes can share this integer using |
63f6a20a | 48 | .BR mmap (2), |
61bba8b4 | 49 | via shared memory segments, or because they share memory space, |
b29c9ff2 | 50 | in which case the application is commonly called multithreaded. |
73d8cece | 51 | .SS Semantics |
fea681da | 52 | .PP |
7fac88a9 | 53 | Any futex operation starts in user space, |
12c71791 | 54 | but it may be necessary to communicate with the kernel using the |
60a90ecd MK |
55 | .BR futex (2) |
56 | system call. | |
fea681da | 57 | .PP |
84c517a4 | 58 | To "up" a futex, execute the proper assembler instructions that |
c13182ef | 59 | will cause the host CPU to atomically increment the integer. |
5fab2e7c | 60 | Afterward, check if it has in fact changed from 0 to 1, in which case |
c13182ef | 61 | there were no waiters and the operation is done. |
24b74457 | 62 | This is the noncontended case which is fast and should be common. |
fea681da | 63 | .PP |
c13182ef MK |
64 | In the contended case, the atomic increment changed the counter |
65 | from \-1 (or some other negative number). | |
66 | If this is detected, there are waiters. | |
7fac88a9 | 67 | User space should now set the counter to 1 and instruct the |
1274071a MK |
68 | kernel to wake up any waiters using the |
69 | .B FUTEX_WAKE | |
70 | operation. | |
fea681da | 71 | .PP |
84c517a4 | 72 | Waiting on a futex, to "down" it, is the reverse operation. |
c13182ef MK |
73 | Atomically decrement the counter and check if it changed to 0, |
74 | in which case the operation is done and the futex was uncontended. | |
75 | In all other circumstances, the process should set the counter to \-1 | |
76 | and request that the kernel wait for another process to up the futex. | |
1274071a MK |
77 | This is done using the |
78 | .B FUTEX_WAIT | |
79 | operation. | |
fea681da | 80 | .PP |
c13182ef | 81 | The |
63f6a20a | 82 | .BR futex (2) |
c13182ef | 83 | system call can optionally be passed a timeout specifying how long |
1e321034 | 84 | the kernel should |
c13182ef | 85 | wait for the futex to be upped. |
b29c9ff2 | 86 | In this case, semantics are more complex and the programmer is referred |
60a90ecd MK |
87 | to |
88 | .BR futex (2) | |
89 | for | |
c13182ef MK |
90 | more details. |
91 | The same holds for asynchronous futex waiting. | |
47297adb | 92 | .SH VERSIONS |
2b2581ee MK |
93 | .PP |
94 | Initial futex support was merged in Linux 2.5.7 | |
95 | but with different semantics from those described above. | |
5fab2e7c | 96 | Current semantics are available from Linux 2.5.40 onward. |
47297adb | 97 | .SH NOTES |
fea681da | 98 | .PP |
61bba8b4 MK |
99 | To reiterate, bare futexes are not intended as an easy-to-use |
100 | abstraction for end users. | |
c13182ef | 101 | Implementors are expected to be assembly literate and to have read |
7fac88a9 | 102 | the sources of the futex user-space library referenced |
fea681da MK |
103 | below. |
104 | .PP | |
60a90ecd MK |
105 | This man page illustrates the most common use of the |
106 | .BR futex (2) | |
61bba8b4 | 107 | primitives; it is by no means the only one. |
d282bb24 | 108 | .\" .SH AUTHORS |
2b2581ee MK |
109 | .\" .PP |
110 | .\" Futexes were designed and worked on by Hubertus Franke | |
111 | .\" (IBM Thomas J. Watson Research Center), | |
112 | .\" Matthew Kirkwood, Ingo Molnar (Red Hat) and | |
113 | .\" Rusty Russell (IBM Linux Technology Center). | |
114 | .\" This page written by bert hubert. | |
47297adb | 115 | .SH SEE ALSO |
8673f915 HS |
116 | .BR clone (2), |
117 | .BR futex (2), | |
118 | .BR get_robust_list (2), | |
119 | .BR set_robust_list (2), | |
120 | .BR set_tid_address (2), | |
121 | .BR pthreads (7) | |
173fe7e7 | 122 | |
2d986c92 | 123 | .IR "Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux" |
c13182ef MK |
124 | (proceedings of the Ottawa Linux Symposium 2002), |
125 | futex example library, futex-*.tar.bz2 | |
608bf950 SK |
126 | .UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ |
127 | .UE . |