-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
15 changed files
with
2,524 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| TARGETS=futex.2 futex.4 futex2.html futex4.html | ||
| SOURCES=futex2.sgml futex4.sgml Makefile | ||
|
|
||
| all: $(TARGETS) futex-manpages.tar.gz | ||
|
|
||
| futex-manpages.tar.gz: $(TARGETS) | ||
| rm -rf futex-manpages | ||
| mkdir futex-manpages | ||
| cp $(TARGETS) $(SOURCES) futex-manpages | ||
| tar cvzf futex-manpages.tar.gz futex-manpages | ||
|
|
||
| clean: | ||
| rm -f *.2 *.4 futex[24].html *~ | ||
|
|
||
| futex.2: futex2.sgml | ||
| docbook2man futex2.sgml | ||
|
|
||
| futex.4: futex4.sgml | ||
| docbook2man futex4.sgml | ||
|
|
||
| futex2.html: futex2.sgml | ||
| docbook2html $< | ||
| mv index.html $@ | ||
|
|
||
| futex4.html: futex4.sgml | ||
| docbook2html $< | ||
| mv index.html $@ | ||
|
|
||
| publish: | ||
| scp $(TARGETS) $(SOURCES) index.html futex-manpages.tar.gz ds9a.nl:/var/www/ds9a.nl/futex-manpages/ |
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| TARGETS=futex.2 futex.4 futex2.html futex4.html | ||
| SOURCES=futex2.sgml futex4.sgml Makefile | ||
|
|
||
| all: $(TARGETS) futex-manpages.tar.gz | ||
|
|
||
| futex-manpages.tar.gz: $(TARGETS) | ||
| rm -rf futex-manpages | ||
| mkdir futex-manpages | ||
| cp $(TARGETS) $(SOURCES) futex-manpages | ||
| tar cvzf futex-manpages.tar.gz futex-manpages | ||
|
|
||
| clean: | ||
| rm -f *.2 *.4 futex[24].html *~ | ||
|
|
||
| futex.2: futex2.sgml | ||
| docbook2man futex2.sgml | ||
|
|
||
| futex.4: futex4.sgml | ||
| docbook2man futex4.sgml | ||
|
|
||
| futex2.html: futex2.sgml | ||
| docbook2html $< | ||
| mv index.html $@ | ||
|
|
||
| futex4.html: futex4.sgml | ||
| docbook2html $< | ||
| mv index.html $@ | ||
|
|
||
| publish: | ||
| scp $(TARGETS) $(SOURCES) index.html futex-manpages.tar.gz ds9a.nl:/var/www/ds9a.nl/futex-manpages/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,140 @@ | ||
| .\" 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 <[email protected]>. | ||
| .TH "FUTEX" "2" "28 May 2004" "" "" | ||
|
|
||
| .SH NAME | ||
| futex \- Fast Userspace Locking system call | ||
| .SH SYNOPSIS | ||
| .sp | ||
| \fB #include <linux/futex.h> | ||
| #include <sys/time.h> | ||
| .sp | ||
| int sys_futex (void *\fIfutex\fB, int \fIop\fB, int \fIval\fB, const struct timespec *\fItimeout\fB, void *\fIfutex2\fB, int \fIval3\fB); | ||
| .sp | ||
| int sys_futex1 (void *\fIfutex\fB, int \fIop\fB, int \fIval\fB, const struct timespec *\fItimeout\fB); | ||
| .sp | ||
| int sys_futex2 (void *\fIfutex1\fB, int \fIop\fB, int \fIval1\fB, int \fIval2\fB, void *\fIfutex2\fB, int \fIval3\fB); | ||
| .sp | ||
| int sys_futex3 (void *\fIfutex1\fB, int \fIop\fB, int \fIval1\fB, int \fIval2\fB, void *\fIfutex2\fB); | ||
| \fR | ||
| .SH "DESCRIPTION" | ||
| .PP | ||
| The \fBsys_futex\fR system call provides a method for | ||
| a program to wait for a value at a given address to change, and a | ||
| method to wake up anyone waiting on a particular address. While the | ||
| addresses for the same memory in separate processes may not be | ||
| identical, the kernel maps them interally so the same memory mapped in | ||
| different locations will correspond for | ||
| \fBsys_futex\fR calls. Futexes are typically used to | ||
| implement the contended case of a lock in shared memory, as | ||
| described in | ||
| \fBfutex\fR(4). | ||
| .PP | ||
| When a | ||
| \fBfutex\fR(4) | ||
| operation does not finish uncontended in userspace, a call needs to be made to the kernel | ||
| to arbitrate. Arbitration can either mean putting the calling process to sleep or, conversely, | ||
| waking a waiting process. | ||
| .PP | ||
| Callers of this function are expected to adhere to the semantics as set out in | ||
| \fBfutex\fR(4). As these | ||
| semantics involve writing non-portable assembly instructions, this in turn | ||
| probably means that most users will in fact be library authors and not general application developers. | ||
| .PP | ||
| The \fIfutex\fR and \fIfutex2\fR arguments need to point at aligned 32 bit integers which store | ||
| the counter. The operation to execute is passed via the \fIop\fR parameter, along with a value \fIval\fR. | ||
| .PP | ||
| Because of historical reasons, the futex system call is highly overloaded. The \fBsys_futex\fR prototype is the canonical | ||
| invocation, while \fBsys_futex1\fR was the original implementation. It should be noted that there is but one system call, | ||
| only the number of the parameters and their names differ. | ||
| .PP | ||
| Five operations are currently defined: | ||
| .TP | ||
| \fBFUTEX_WAIT\fR | ||
| This operation atomically verifies that the futex address still contains the value given, and sleeps awaiting \fIFUTEX_WAKE\fR on this futex address. If the | ||
| \fItimeout\fR argument is non-NULL, its contents describe the maximum duration | ||
| of the wait, which is infinite otherwise. For \fBfutex\fR(4), this call is executed if decrementing the count gave a negative value (indicating contention), and will sleep until another process releases the futex and executes the FUTEX_WAKE operation. | ||
|
|
||
| Uses the \fBsys_futex1()\fR prototype. | ||
| .TP | ||
| \fBFUTEX_WAKE\fR | ||
| This operation wakes at most \fIval\fR | ||
| processes waiting on this futex address (ie. inside | ||
| \fIFUTEX_WAIT\fR). For \fBfutex\fR(4), this is executed if incrementing | ||
| the count showed that there were waiters, once the futex value has been set to 1 (indicating that it is available). | ||
|
|
||
| Uses the \fBsys_futex1()\fR prototype. | ||
| .TP | ||
| \fBFUTEX_CMP_REQUEUE\fR | ||
| Identical to FUTEX_WAKE except that any processes in excess of the number specified in \fIval\fR are not woken up | ||
| but moved to the futex passed in \fIfutex2\fR. The number of processes to move is capped by | ||
| \fIval2\fR. Passing 0 makes this operation degenerate into \fIFUTEX_WAKE\fR. | ||
|
|
||
| This operation can be used to efficiently implement | ||
| \fBpthread_cond_broadcast\fR(3) on larger SMP systems. | ||
|
|
||
| The value passed in \fIval3\fR is compared to that of the futex, exactly like \fIFUTEX_WAIT\fR. | ||
| For full details which are outside the scope of this manpage, see the 'Futexes are tricky' article referenced below. | ||
|
|
||
| Available since kernel version 2.6.7 and uses the \fBsys_futex2()\fR prototype. | ||
| .TP | ||
| \fBFUTEX_REQUEUE\fR | ||
| Identical to \fIFUTEX_CMP_REQUEUE\fR except that it does not use \fIval3\fR, and has been shown | ||
| to be prone to race conditions when used to implement | ||
| \fBpthread_cond_broadcast\fR(3). | ||
| Uses the \fBsys_futex3()\fR prototype. | ||
| .TP | ||
| \fBFUTEX_FD\fR | ||
| To support asynchronous wakeups, this operation associates a file descriptor with a futex. | ||
| If another process executes a FUTEX_WAKE, the process will receive the signal number that | ||
| was passed in \fIval\fR. The calling process must close the returned file | ||
| descriptor after use. | ||
|
|
||
| To prevent race conditions, the caller should test if the futex has been upped after FUTEX_FD | ||
| returns. | ||
|
|
||
| Uses the \fBsys_futex1()\fR prototype. | ||
| .SH "RETURN VALUE" | ||
| .PP | ||
| Depending on which operation was executed, the returned value has different meanings. | ||
| .TP | ||
| \fBFUTEX_WAIT\fR | ||
| Returns 0 if the process was woken by a FUTEX_WAKE call. In case of timeout, -ETIMEDOUT is returned. If the futex was not equal to the expected value, the operation returns -EWOULDBLOCK. Signals (or other spurious wakeups) cause FUTEX_WAIT to return -EINTR. | ||
| .TP | ||
| \fBFUTEX_WAKE and FUTEX_REQUEUE\fR | ||
| Returns the number of processes woken up (which equals the number of FUTEX_WAIT operations returning 0). | ||
| .TP | ||
| \fBFUTEX_CMP_REQUEUE\fR | ||
| Returns -EAGAIN if the mutex did not have the value specified in \fIval3\fR. Otherwise returns the number | ||
| of processes woken up. If this is larger than \fIvar1\fR, processes have been requeued. | ||
| .TP | ||
| \fBFUTEX_FD\fR | ||
| Returns the new file descriptor associated with the futex. | ||
| .PP | ||
| All operations may return -EINVAL in case of unaligned futexes, as well as -EFAULT, -EPERM, -EACCESS when passing pointers to bad or | ||
| inaccessible memory. | ||
| .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. | ||
| .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, FUTEX_REQUEUE was added around 2.5.70, whilst | ||
| FUTEX_CMP_REQUEUE was added in 2.6.7. | ||
| .SH "SEE ALSO" | ||
| .PP | ||
| \fBfutex\fR(4), | ||
| `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.nl.kernel.org:/pub/linux/kernel/people/rusty/>, | ||
| `Futexes are tricky' at http://people.redhat.com/drepper/futex.pdf <URL:http://people.redhat.com/drepper/futex.pdf> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| .\" 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 <[email protected]>. | ||
| .TH "FUTEX" "4" "28 May 2004" "" "" | ||
|
|
||
| .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, while additional functionality became available around | ||
| 2.5.70 (FUTEX_REQUEUE) and 2.6.7 (FUTEX_CMP_REQUEUE). | ||
| .SH "SEE ALSO" | ||
| .PP | ||
| \fBfutex\fR(4), | ||
| `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.nl.kernel.org:/pub/linux/kernel/people/rusty/>, | ||
| `Futexes are tricky' at http://people.redhat.com/drepper/futex.pdf <URL:http://people.redhat.com/drepper/futex.pdf> |
Oops, something went wrong.