| .\" This manpage has been automatically generated by docbook2man |
| .\" from a DocBook document. This tool can be found at: |
| .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> |
| .\" Please send any bug reports, improvements, comments, patches, |
| .\" etc. to Steve Cheng <steve@ggi-project.org>. |
| .\" |
| .\" %%%LICENSE_START(MIT) |
| .\" This page is made available under the MIT license. |
| .\" %%%LICENSE_END |
| .\" |
| .TH FUTEX 7 2015-12-28 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| futex \- fast user-space locking |
| .SH SYNOPSIS |
| .nf |
| .B #include <linux/futex.h> |
| .fi |
| .SH DESCRIPTION |
| .PP |
| The Linux kernel provides futexes ("Fast user-space mutexes") |
| as a building block for fast user-space |
| locking and semaphores. |
| Futexes are very basic and lend themselves well for building higher-level |
| locking abstractions such as |
| mutexes, condition variables, read-write locks, barriers, and semaphores. |
| .PP |
| Most programmers will in fact not be using futexes directly but will |
| instead rely on system libraries built on them, |
| such as the Native POSIX Thread Library (NPTL) (see |
| .BR pthreads (7)). |
| .PP |
| A futex is identified by a piece of memory which can be |
| shared between processes or threads. |
| In these different processes, the futex need not have identical addresses. |
| In its bare form, a futex has semaphore semantics; |
| it is a counter that can be incremented and decremented atomically; |
| processes can wait for the value to become positive. |
| .PP |
| Futex operation occurs entirely in user space for the noncontended case. |
| The kernel is involved only to arbitrate the contended case. |
| As any sane design will strive for noncontention, |
| futexes are also optimized for this situation. |
| .PP |
| In its bare form, a futex is an aligned integer which is |
| touched only by atomic assembler instructions. |
| This integer is four bytes long on all platforms. |
| Processes can share this integer using |
| .BR mmap (2), |
| via shared memory segments, or because they share memory space, |
| in which case the application is commonly called multithreaded. |
| .SS Semantics |
| .PP |
| Any futex operation starts in user space, |
| but it may be necessary to communicate with the kernel using the |
| .BR futex (2) |
| system call. |
| .PP |
| To "up" a futex, execute the proper assembler instructions that |
| will cause the host CPU to atomically increment the integer. |
| Afterward, check if it has in fact changed from 0 to 1, in which case |
| there were no waiters and the operation is done. |
| This is the noncontended case which is fast and should be common. |
| .PP |
| In the contended case, the atomic increment changed the counter |
| from \-1 (or some other negative number). |
| If this is detected, there are waiters. |
| User space should now set the counter to 1 and instruct the |
| kernel to wake up any waiters using the |
| .B FUTEX_WAKE |
| operation. |
| .PP |
| Waiting on a futex, to "down" it, is the reverse operation. |
| Atomically decrement the counter and check if it changed to 0, |
| in which case the operation is done and the futex was uncontended. |
| In all other circumstances, the process should set the counter to \-1 |
| and request that the kernel wait for another process to up the futex. |
| This is done using the |
| .B FUTEX_WAIT |
| operation. |
| .PP |
| The |
| .BR futex (2) |
| system call can optionally be passed a timeout specifying how long |
| the kernel should |
| wait for the futex to be upped. |
| In this case, semantics are more complex and the programmer is referred |
| to |
| .BR futex (2) |
| for |
| more details. |
| The same holds for asynchronous futex waiting. |
| .SH VERSIONS |
| .PP |
| Initial futex support was merged in Linux 2.5.7 |
| but with different semantics from those described above. |
| Current semantics are available from Linux 2.5.40 onward. |
| .SH NOTES |
| .PP |
| To reiterate, bare futexes are not intended as an easy-to-use |
| abstraction for end users. |
| Implementors are expected to be assembly literate and to have read |
| the sources of the futex user-space library referenced |
| below. |
| .PP |
| This man page illustrates the most common use of the |
| .BR futex (2) |
| primitives; it is by no means the only one. |
| .\" .SH AUTHORS |
| .\" .PP |
| .\" Futexes were designed and worked on by Hubertus Franke |
| .\" (IBM Thomas J. Watson Research Center), |
| .\" Matthew Kirkwood, Ingo Molnar (Red Hat) and |
| .\" Rusty Russell (IBM Linux Technology Center). |
| .\" This page written by bert hubert. |
| .SH SEE ALSO |
| .BR clone (2), |
| .BR futex (2), |
| .BR get_robust_list (2), |
| .BR set_robust_list (2), |
| .BR set_tid_address (2), |
| .BR pthreads (7) |
| |
| .IR "Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux" |
| (proceedings of the Ottawa Linux Symposium 2002), |
| futex example library, futex-*.tar.bz2 |
| .UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ |
| .UE . |