1 files changed, 79 insertions, 0 deletions
diff --git a/man4/futex.4 b/man4/futex.4
new file mode 100644
index 000000000..e99322650
--- /dev/null
+++ b/man4/futex.4
@@ -0,0 +1,79 @@
+.\" 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>.
+.TH FUTEX 4 2002-12-31 "" "Linux Programmer's Manual"
+.SH NAME
+futex \- Fast Userspace Locking
+.SH SYNOPSIS
+.nf
+#include <linux/futex.h>
+.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 
+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, 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; 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-contension, 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 over mmap, via shared 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, 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. 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 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. This is done using the FUTEX_WAIT operation.
+.PP
+The futex 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 \fBfutex\fR(2) for
+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 the sources of the futex userspace library referenced
+below.
+.PP
+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). This page written
+by bert hubert.
+.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 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 <URL:ftp://ftp.kernel.org:/pub/linux/kernel/people/rusty/>.