futex.2: Expand description of FUTEX_CMP_REQUEUE

With some help from "Futexes are tricky" bt Ulrich Drepper.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/futex.2

@@ -464,28 +464,73 @@ The argument
 is ignored.
 .TP
 .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)"
-There was a race in the intended use of
+This operation was added as a replacement for the earlier
 .BR FUTEX_REQUEUE ,
-so
-.B FUTEX_CMP_REQUEUE
-was introduced.
-This operation is similar to
+because that operation was racy for its intended use.
+
+As with
 .BR FUTEX_REQUEUE ,
-but first checks whether the location
+the
+.BR FUTEX_CMP_REQUEUE
+operation is used to avoid a "thundering herd" effect when
+.B FUTEX_WAKE
+is used and all processes woken up need to acquire another futex.
+It differs from
+.BR FUTEX_REQUEUE
+in that it first checks whether the location
 .I uaddr
 still contains the value
 .IR val3 .
 If not, the operation fails with the error
 .BR EAGAIN .
+.\" FIXME I added the following sentence on rational for FUTEX_CMP_REQUEUE.
+.\"       Is it correct? SHould it be expanded?
+This additional feature of
+.BR FUTEX_CMP_REQUEUE
+can be used by the caller to (atomically) detect changes
+in the value of the target futex at
+.IR uaddr2 .
 
-The arguments
-.IR val ,
-.IR uaddr ,
-.IR uaddr2 ,
-and
+The operation wakes up a maximum of
+.I val
+waiters that are waiting on the futex at
+.IR uaddr .
+If there are more than
+.I val
+waiters, then the remaining waiters are removed
+from the wait queue of the source futex at
+.I uaddr
+and added to the wait queue of the target futex at
+.IR uaddr2 .
+The
 .I timeout
-are as for
-.BR FUTEX_REQUEUE .
+argument is (ab)used to specify a cap on the number of waiters
+that are requeued to the futex at
+.IR uaddr2 ;
+the kernel casts the
+.I timeout
+value to
+.IR u32 .
+
+.\" FIXME Please review the following new paragraph to see if it is
+.\"       accurate.
+Typical values to specify for
+.I val
+are 0 or or 1.
+(Specifying
+.BR INT_MAX
+is not useful, because it would make the
+.BR FUTEX_CMP_REQUEUE
+operation equivalent to
+.BR FUTEX_WAKE .)
+The cap value specified via the (abused)
+.I timeout
+argument is typically either 1 or
+.BR INT_MAX .
+(Specifying the argument as 0 is not useful, because it would make the
+.BR FUTEX_CMP_REQUEUE
+operation equivalent to
+.BR FUTEX_WAIT .)
 .TP
 .BR FUTEX_CMP_REQUEUE_PI " (since Linux 2.6.31)"
 .\" commit 52400ba946759af28442dee6265c5c0180ac7122
@@ -520,7 +565,12 @@ Returns the new file descriptor associated with the futex.
 Returns the number of processes woken up.
 .TP
 .B FUTEX_CMP_REQUEUE
-Returns the number of processes woken up.
+Returns the total number of processes woken up or requeued to the futex at
+.IR uaddr2 .
+If this value is greater than
+.IR val ,
+then difference is the number of waiters requeued to the futex at
+.IR uaddr2 .
 .\"
 .\" FIXME Add success returns for other operations
 .SH ERRORS