Re: bug in futex.2, FUTEX_CMP_REQUEUE

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

On 5/27/25 8:01 AM, Alejandro Colomar wrote:
> [Added a few people to CC]
> 
> Hi Jens,
> 
> On Tue, May 27, 2025 at 11:53:03AM +0200, 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?
> 
> That seems to be a typo.  It seems to me that it would be equivalent to
> FUTEX_WAKE (just like a few sentences before).

As noted in my earlier response, this is not a typo?

> <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=74aa7971e5148f67d5def9977ed87cced638016a>
> 
> 	commit 74aa7971e5148f67d5def9977ed87cced638016a
> 	Author: Alejandro Colomar <alx@kernel.org>
> 	Date:   Tue May 27 13:07:19 2025 +0200
> 
> 	    man/man2/futex.2: tfix
> 	
> 	    Fixes: 3dfcc11d4630 (2015-12-15; "futex.2: Expand description of FUTEX_CMP_REQUEUE")
> 	    Fixes: 8297383e9eeb (2015-12-15; "futex.2: Clean-ups and FIXME removeal after feedback from Thomas Gleixner")
> 	    Reported-by: Jens Gustedt <jens.gustedt@inria.fr>
> 	    Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> 	diff --git a/man/man2/futex.2 b/man/man2/futex.2
> 	index 128612ee1..9a15a0fdb 100644
> 	--- a/man/man2/futex.2
> 	+++ b/man/man2/futex.2
> 	@@ -501,7 +501,7 @@ .SS Futex operations
> 	 (Specifying the argument as 0 is not useful, because it would make the
> 	 .B FUTEX_CMP_REQUEUE
> 	 operation equivalent to
> 	-.BR FUTEX_WAIT .)
> 	+.BR FUTEX_WAKE .)

This is incorrect.

A value of zero means no tasks are woken.

The key question here is how do you define or document the semantics
of the linked WAKE/WAIT that puts the tasks in the new queue.

-- 
Cheers,
Carlos.