diff options
Diffstat (limited to 'upstream/archlinux/man7/futex.7')
| -rw-r--r-- | upstream/archlinux/man7/futex.7 | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/upstream/archlinux/man7/futex.7 b/upstream/archlinux/man7/futex.7 new file mode 100644 index 00000000..ca92df1b --- /dev/null +++ b/upstream/archlinux/man7/futex.7 @@ -0,0 +1,121 @@ +.\" 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>. +.\" +.\" SPDX-License-Identifier: MIT +.\" +.TH futex 7 2023-10-31 "Linux man-pages 6.06" +.SH NAME +futex \- fast user-space locking +.SH SYNOPSIS +.nf +.B #include <linux/futex.h> +.fi +.SH DESCRIPTION +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. +.P +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)). +.P +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. +.P +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. +.P +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 +Any futex operation starts in user space, +but it may be necessary to communicate with the kernel using the +.BR futex (2) +system call. +.P +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. +.P +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. +.P +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. +.P +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 +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 +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. +.P +This man page illustrates the most common use of the +.BR futex (2) +primitives; it is by no means the only one. +.\" .SH AUTHORS +.\" .P +.\" 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) +.P +.I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux +(proceedings of the Ottawa Linux Symposium 2002), +futex example library, futex-*.tar.bz2 +.UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ +.UE . |