[PATCH] man7/futex.7 remove buggy example

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



This example use of futex(2) is buggy, as described in this paper
(which is referenced in futex(2)):
https://www.akkadia.org/drepper/futex.pdf
---
 man7/futex.7 | 127 ---------------------------------------------------
 1 file changed, 127 deletions(-)
 delete mode 100644 man7/futex.7

diff --git a/man7/futex.7 b/man7/futex.7
deleted file mode 100644
index f59725b61..000000000
--- a/man7/futex.7
+++ /dev/null
@@ -1,127 +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@xxxxxxxxxxxxxxx>.
-.\"
-.\" %%%LICENSE_START(MIT)
-.\" This page is made available under the MIT license.
-.\" %%%LICENSE_END
-.\"
-.TH FUTEX 7 2017-09-15 "Linux" "Linux Programmer's Manual"
-.SH NAME
-futex \- fast user-space locking
-.SH SYNOPSIS
-.nf
-.B #include <linux/futex.h>
-.fi
-.SH DESCRIPTION
-.PP
-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.
-.PP
-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)).
-.PP
-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.
-.PP
-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.
-.PP
-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
-.PP
-Any futex operation starts in user space,
-but it may be necessary to communicate with the kernel using the
-.BR futex (2)
-system call.
-.PP
-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.
-.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.
-User space should now set the counter to 1 and instruct the
-kernel to wake up any waiters using the
-.B 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
-.B FUTEX_WAIT
-operation.
-.PP
-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
-.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 onward.
-.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 user-space library referenced
-below.
-.PP
-This man page illustrates the most common use of the
-.BR futex (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 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)
-.PP
-.IR "Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux"
-(proceedings of the Ottawa Linux Symposium 2002),
-futex example library, futex-*.tar.bz2
-.UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
-.UE .
-- 
2.17.1




[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux