futex.2: Wrap sentences at line boundaries

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2015-03-03 07:22:31 +01:00
parent 74f58a643b
commit 077981d467
1 changed files with 37 additions and 20 deletions

View File

@ -41,11 +41,13 @@ There is no glibc wrapper for this system call; see NOTES.
The
.BR futex ()
system call provides a method for waiting until a certain condition becomes
true. It is typically used as a blocking construct in the context of
true.
It is typically used as a blocking construct in the context of
shared-memory synchronization: The program implements the majority of the
synchronization in user space, and uses one of operations of the system call
when it is likely that it has to block for a longer time until the condition
becomes true. The program uses another operation of the system call to wake
becomes true.
The program uses another operation of the system call to wake
anyone waiting for a particular condition.
The condition is represented by the futex word, which is an address in memory
@ -61,33 +63,41 @@ calls.)
When executing a futex operation that requests to block a thread, the kernel
will only block if the futex word has the value that the calling thread
supplied as expected value. The load from the futex word, the comparison with
the expected value, and the actual blocking will happen atomically and totally
supplied as expected value.
The load from the futex word, the comparison with
the expected value,
and the actual blocking will happen atomically and totally
ordered with respect to concurrently executing futex operations on the same
futex word, such as operations that wake threads blocked on this futex word.
Thus, the futex word is used to connect the synchronization in user space with
the implementation of blocking by the kernel; similar to an atomic
compare-and-exchange operation that potentially changes shared memory,
blocking via a futex is an atomic compare-and-block operation. See NOTES for
blocking via a futex is an atomic compare-and-block operation.
See NOTES for
a detailed specification of the synchronization semantics.
One example use of futexes is implementing locks. The state of the lock (i.e.,
One example use of futexes is implementing locks.
The state of the lock (i.e.,
acquired or not acquired) can be represented as an atomically accessed flag
in shared memory. In the uncontended case, a thread can access or modify the
in shared memory.
In the uncontended case, a thread can access or modify the
lock state with atomic instructions, for example atomically changing it from
not acquired to acquired using an atomic compare-and-exchange instruction. If
a thread cannot acquire a lock because it is already acquired by another
not acquired to acquired using an atomic compare-and-exchange instruction.
If a thread cannot acquire a lock because it is already acquired by another
thread, it can request to block if and only the lock is still acquired by
using the lock's flag as futex word and expecting a value that represents the
acquired state. When releasing the lock, a thread has to first reset the
acquired state.
When releasing the lock, a thread has to first reset the
lock state to not acquired and then execute the futex operation that wakes
one thread blocked on the futex word that is the lock's flag (this can be
be further optimized to avoid unnecessary wake-ups). See
be further optimized to avoid unnecessary wake-ups).cw
See
.BR futex (7)
for more detail on how to use futexes.
Besides the basic wait and wake-up futex functionality, there are further
futex operations aimed at supporting more complex use cases. Also note that
futex operations aimed at supporting more complex use cases.
Also note that
no explicit initialization or destruction are necessary to use futexes; the
kernel maintains a futex (i.e., the kernel-internal implementation artifact)
only while operations such as
@ -97,7 +107,8 @@ described below, are being performed on a particular futex word.
.SS Arguments
The
.I uaddr
argument points to the futex word. On all platforms, futexes are four-byte
argument points to the futex word.
On all platforms, futexes are four-byte
integers that must be aligned on a four-byte boundary.
The operation to perform on the futex is specified in the
.I futex_op
@ -212,11 +223,14 @@ still contains the expected value
.IR val ,
and if so, then sleeps awaiting
.B FUTEX_WAKE
on the futex word. The load of the value of the futex word is an atomic memory
on the futex word.
The load of the value of the futex word is an atomic memory
access (i.e., using atomic machine instructions of the respective
architecture). This load, the comparison with the expected value, and
architecture).
This load, the comparison with the expected value, and
starting to sleep are performed atomically and totally ordered with respect
to other futex operations on the same futex word. If the thread starts to
to other futex operations on the same futex word.
If the thread starts to
sleep, it is considered a waiter on this futex word.
If the futex value does not match
.IR val ,
@ -398,7 +412,8 @@ that are requeued to the futex at
The load from
.I uaddr
is an atomic memory access (i.e., using atomic machine instructions of the
respective architecture). This load, the comparison with
respective architecture).
This load, the comparison with
.IR val3 ,
and the requeueing of any waiters are performed atomically and totally ordered
with respect to other operations on the same futex word.
@ -1090,7 +1105,8 @@ The return value on success depends on the operation,
as described in the following list:
.TP
.B FUTEX_WAIT
Returns 0 if the caller was woken up. Note that a wake-up can also be
Returns 0 if the caller was woken up.
Note that a wake-up can also be
caused by common futex usage patterns in unrelated code that happened to have
previously used the futex word's memory location (e.g., typical futex-based
implementations of Pthreads mutexes can cause this under some conditions).
@ -1125,7 +1141,8 @@ and
.IR uaddr2 .
.TP
.B FUTEX_WAIT_BITSET
Returns 0 if the caller was woken up. See
Returns 0 if the caller was woken up.
See
.B FUTEX_WAIT
for how to interpret this correctly in practice.
.TP
@ -1408,7 +1425,7 @@ nor
.BR FUTEX_WAIT_REQUEUE_PI )
A run-time check determined that the operation is not available.
The PI futex operations are not implemented on all architectures and
are not supported on some CPU variants.
are not supported on some CPU variants.
.TP
.BR EPERM
.RB ( FUTEX_LOCK_PI ,