This example use of futex(2) is buggy, as described in this paper (which is referenced in futex(2)): https://www.akkadia.org/drepper/futex.pdf --- man7/futex.7 | 127 --------------------------------------------------- 1 file changed, 127 deletions(-) delete mode 100644 man7/futex.7 diff --git a/man7/futex.7 b/man7/futex.7 deleted file mode 100644 index f59725b61..000000000 --- a/man7/futex.7 +++ /dev/null @@ -1,127 +0,0 @@ -.\" 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@xxxxxxxxxxxxxxx>. -.\" -.\" %%%LICENSE_START(MIT) -.\" This page is made available under the MIT license. -.\" %%%LICENSE_END -.\" -.TH FUTEX 7 2017-09-15 "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) -.PP -.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 . -- 2.17.1
