Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Carlos O'Donell <carlos@redhat.com>]

On 5/27/25 5:53 AM, Jₑₙₛ Gustedt wrote:
> Hello Alex and everybody,
> I stumbled upon this confusing text in the futex man page
> 
>    Typical values to specify for `val` are `0` or `1`.  (Specifying
>    `INT_MAX` is not useful, because it would make the
>    `FUTEX_CMP_REQUEUE` operation equivalent to `FUTEX_WAKE`.)  The
>    limit value specified via `val2` is typically either `1` or
>    `INT_MAX`.  (Specifying the argument as `0` is not useful, because
>    it would make the `FUTEX_CMP_REQUEUE` operation equivalent to
>    `FUTEX_WAIT`.)
> 
>    The `FUTEX_CMP_REQUEUE` operation was added as a replacement for the
>    earlier `FUTEX_REQUEUE`.  The difference is that the check of the
>    value at `uaddr` can be used to ensure that requeueing happens only
>    under certain conditions, which allows race conditions to be avoided
>    in certain use cases.
> 
> 
> This has several issues, the most severe beeing the word `FUTEX_WAIT`.
> 
> - How can an operation that only does wakes, ever be equivalent to a
>    wait?

My opinion is that the text is correct.

The operation can WAKE tasks.

The operation can also cause tasks to WAIT in a *different* queue.

If zero tasks are woken (val==0), and all tasks moved to WAIT on a
different queue, then the operation has WAIT semantics on the
new and distinct queue.

Since there is no concept of MOVING in the futex, you could
conceptually discuss this as a linked WAKE/WAIT sequence i.e.
REQUEUE, which is what the operation does.

> But then, even if we assume that both subphrases mean to talk about
> `FUTEX_WAKE`, the assumption that this can ever be equivalent is
> bogus. In fact `FUTEX_CMP_REQUEUE` checks for `val3` still being
> pressent in the memory location, which `FUTEX_WAKE` doesn't.

Both subphrases are not meant to talk about FUTEX_WAKE.

> So I think that specifying any of the values that are pointed out in
> this paragraph can make sense, because of the added comparison to
> `val3`.
> 
> I suggest to change to something along
> 
>    The limit value specified via `val2` is typically either `1` or
>    `INT_MAX`. Specifying the argument as `0` makes the
>    `FUTEX_CMP_REQUEUE` operation equivalent to `FUTEX_WAKE`, only that
>    the operation then also ensures an atomic check for `*uaddr ==
>    val3`.  Typical values to specify for `val` are `0`, `1` or
>    `INT_MAX`.
> 
> 
>    The `FUTEX_CMP_REQUEUE` operation was added as a replacement for the
>    earlier `FUTEX_REQUEUE`.  The difference is that the check of the
>    value at `uaddr` can be used to ensure that requeueing happens only
>    under certain conditions, which allows race conditions to be avoided
>    in certain use cases.  In particular, a combination of `val == 1`
>    and `val2 == 0` is similar to the operation of `pthread_cond_signal`
>    with an additional check for `val3`; `val == 1` and `val2 ==
>    INT_MAX` is similar to `pthread_cond_broadcast` with such a check.

Does my clarification above obviate the need to make any changes?

Or do you think the text needs further clarification?

-- 
Cheers,
Carlos.