From 077981d4678b26e927c35954d1bd698aaaedf0b1 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Tue, 3 Mar 2015 07:22:31 +0100 Subject: [PATCH] futex.2: Wrap sentences at line boundaries Signed-off-by: Michael Kerrisk --- man2/futex.2 | 57 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 20 deletions(-) diff --git a/man2/futex.2 b/man2/futex.2 index d8eb82344..8164aa043 100644 --- a/man2/futex.2 +++ b/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 ,