diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-04-12 22:42:49 +0000 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-04-12 22:42:49 +0000 |
| commit | c13182efa3b3d77f2563034c8212c0ca798243ca (patch) | |
| tree | e7652b26018b7c22cd6a4e4b41404dfaab911303 /man7/futex.7 | |
| parent | 4174ff5658082832c2ed511720f18881b3a80a34 (diff) | |
| download | man-pages-c13182efa3b3d77f2563034c8212c0ca798243ca.tar.gz | |
Wrapped long lines, wrapped at sentence boundaries; stripped trailing
white space.
Diffstat (limited to 'man7/futex.7')
| -rw-r--r-- | man7/futex.7 | 113 |
1 files changed, 57 insertions, 56 deletions
diff --git a/man7/futex.7 b/man7/futex.7 index b1ddc3ebfe..645de63b06 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -1,9 +1,9 @@ .\" This page is made available under the MIT license. .\" -.\" This manpage has been automatically generated by docbook2man +.\" 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, +.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> +.\" Please send any bug reports, improvements, comments, patches, .\" etc. to Steve Cheng <steve@ggi-project.org>. .TH FUTEX 7 2002-12-31 "" "Linux Programmer's Manual" .SH NAME @@ -14,96 +14,97 @@ futex \- Fast Userspace Locking .fi .SH DESCRIPTION .PP -The Linux kernel provides futexes ('Fast Userspace muTexes') -as a building block for fast userspace -locking and semaphores. -Futexes are very basic and lend themselves well for building higher level +The Linux kernel provides futexes ('Fast Userspace muTexes') +as a building block for fast userspace +locking and semaphores. +Futexes are very basic and lend themselves well for building higher level locking abstractions such as POSIX mutexes. .PP -This page does not set out to document all design decisions -but restricts itself to issues relevant for -application and library development. -Most programmers will in fact not be using futexes directly but -instead rely on system libraries built on them, +This page does not set out to document all design decisions +but restricts itself to issues relevant for +application and library development. +Most programmers will in fact not be using futexes directly but +instead rely on system libraries built on them, such as the NPTL pthreads implementation. .PP -A futex is identified by a piece of memory which can be -shared between different processes. -In these different processes, it 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; +A futex is identified by a piece of memory which can be +shared between different processes. +In these different processes, it 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 is entirely userspace for the non-contended case. -The kernel is only involved to arbitrate the contended case. -As any sane design will strive for non-contention, +Futex operation is entirely userspace for the non-contended case. +The kernel is only involved to arbitrate the contended case. +As any sane design will strive for non-contention, futexes are also optimised for this situation. .PP -In its bare form, a futex is an aligned integer which is -only touched by atomic assembler instructions. -Processes can share this integer using -.BR mmap (), -via shared memory segments or because they share memory space, +In its bare form, a futex is an aligned integer which is +only touched by atomic assembler instructions. +Processes can share this integer using +.BR mmap (), +via shared memory segments or because they share memory space, in which case the application is commonly called multithreaded. .SH "SEMANTICS" .PP -Any futex operation starts in userspace, +Any futex operation starts in userspace, but it may necessary to communicate with the kernel using the \fBfutex\fR(2) system call. .PP -To 'up' a futex, execute the proper assembler instructions that -will cause the host CPU to atomically increment the integer. -Afterwards, check if it has in fact changed from 0 to 1, in which case -there were no waiters and the operation is done. +To 'up' a futex, execute the proper assembler instructions that +will cause the host CPU to atomically increment the integer. +Afterwards, 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 non-contended 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. -Userspace should now set the counter to 1 and instruct the +In the contended case, the atomic increment changed the counter +from \-1 (or some other negative number). +If this is detected, there are waiters. +Userspace should now set the counter to 1 and instruct the kernel to wake up any waiters using the 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. +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 FUTEX_WAIT operation. .PP -The -.BR futex () -system call can optionally be passed a timeout specifying how long +The +.BR futex () +system call can optionally be passed a timeout specifying how long the kernel should -wait for the futex to be upped. +wait for the futex to be upped. In this case, semantics are more complex and the programmer is referred to \fBfutex\fR(2) for -more details. The same holds for asynchronous futex waiting. +more details. +The same holds for asynchronous futex waiting. .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 +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 userspace library referenced below. .PP -This man page illustrates the most common use of the \fBfutex\fR(2) +This man page illustrates the most common use of the \fBfutex\fR(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). +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 "VERSIONS" .PP -Initial futex support was merged in Linux 2.5.7 +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 onwards. .SH "SEE ALSO" .PP \fBfutex\fR(2), -`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' -(proceedings of the Ottawa Linux Symposium 2002), -futex example library, futex-*.tar.bz2 +`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' +(proceedings of the Ottawa Linux Symposium 2002), +futex example library, futex-*.tar.bz2 <URL:ftp://ftp.kernel.org:/pub/linux/kernel/people/rusty/>. |