mirror of https://github.com/mkerrisk/man-pages
futex.2: Wrap sentences at line boundaries
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
74f58a643b
commit
077981d467
57
man2/futex.2
57
man2/futex.2
|
@ -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 ,
|
||||
|
|
Loading…
Reference in New Issue