summaryrefslogtreecommitdiffstats
path: root/man7/futex.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/futex.7')
-rw-r--r--man7/futex.7121
1 files changed, 0 insertions, 121 deletions
diff --git a/man7/futex.7 b/man7/futex.7
deleted file mode 100644
index 52af91f..0000000
--- a/man7/futex.7
+++ /dev/null
@@ -1,121 +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@ggi-project.org>.
-.\"
-.\" SPDX-License-Identifier: MIT
-.\"
-.TH futex 7 2023-10-31 "Linux man-pages 6.7"
-.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 .