futex: Clarify comment in futex_requeue()

[sfrench/cifs-2.6.git] / kernel / futex.c

diff --git a/kernel/futex.c b/kernel/futex.c
index 6cb6b5db3e2443494a985ca70dceda19426711b4..8d8bad5e07bb60aea0a3fb36bb4208cfea4b21c7 100644 (file)
--- a/kernel/futex.c
+++ b/kernel/futex.c
@@ -1939,15 +1939,27 @@ static int futex_requeue(u32 __user *uaddr1, unsigned int flags,
                 */
                if (refill_pi_state_cache())
                        return -ENOMEM;
+
                /*
-                * requeue_pi must wake as many tasks as it can, up to nr_wake
-                * + nr_requeue, since it acquires the rt_mutex prior to
-                * returning to userspace, so as to not leave the rt_mutex with
-                * waiters and no owner.  However, second and third wake-ups
-                * cannot be predicted as they involve race conditions with the
-                * first wake and a fault while looking up the pi_state.  Both
-                * pthread_cond_signal() and pthread_cond_broadcast() should
-                * use nr_wake=1.
+                * futex_requeue() allows the caller to define the number
+                * of waiters to wake up via the @nr_wake argument. With
+                * REQUEUE_PI, waking up more than one waiter is creating
+                * more problems than it solves. Waking up a waiter makes
+                * only sense if the PI futex @uaddr2 is uncontended as
+                * this allows the requeue code to acquire the futex
+                * @uaddr2 before waking the waiter. The waiter can then
+                * return to user space without further action. A secondary
+                * wakeup would just make the futex_wait_requeue_pi()
+                * handling more complex, because that code would have to
+                * look up pi_state and do more or less all the handling
+                * which the requeue code has to do for the to be requeued
+                * waiters. So restrict the number of waiters to wake to
+                * one, and only wake it up when the PI futex is
+                * uncontended. Otherwise requeue it and let the unlock of
+                * the PI futex handle the wakeup.
+                *
+                * All REQUEUE_PI users, e.g. pthread_cond_signal() and
+                * pthread_cond_broadcast() must use nr_wake=1.
                 */
                if (nr_wake != 1)
                        return -EINVAL;