bug in futex.2, FUTEX_CMP_REQUEUE

bug in futex.2, FUTEX_CMP_REQUEUE

[Jₑₙₛ Gustedt]

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?

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.

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.

Thanks
Jₑₙₛ

-- 
:: ICube :::::::::::::::::::::::::::::: deputy director ::
:: Université de Strasbourg :::::::::::::::::::::: ICPS ::
:: INRIA antenne de Strasbourg :::::::::::::::::: Camus ::
:: INRIA PIQ program Strasbourg :::::::::: piq.inria.fr ::
:: :::::::::::::::::::::::::::::::::::: ☎ +33 368854536 ::
:: https://icube-icps.unistra.fr/index.php/Jens_Gustedt ::

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Carlos O'Donell]

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.

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4555 bytes --]

[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).

> 
> But then, even if we assume that both subphrases mean to talk about
> `FUTEX_WAKE`,

Yep.

I've applied this patch:

<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 .)
	 .IP
	 The
	 .B FUTEX_CMP_REQUEUE

> 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.

Yep, we should document that.

> 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.

I'll wait a little bit before doing anything to see if someone else
wants to chime in.  I never used futex(2), so can't comment much.  It
sounds more or less reasonable.

In the meantime, I see some other things that need updates regarding
futex(2), so I'll work on that (e.g., the futex_requeue() system call).


Have a lovely day!
Alex

> 
> Thanks
> Jₑₙₛ
> 
> -- 
> :: ICube :::::::::::::::::::::::::::::: deputy director ::
> :: Université de Strasbourg :::::::::::::::::::::: ICPS ::
> :: INRIA antenne de Strasbourg :::::::::::::::::: Camus ::
> :: INRIA PIQ program Strasbourg :::::::::: piq.inria.fr ::
> :: :::::::::::::::::::::::::::::::::::: ☎ +33 368854536 ::
> :: https://icube-icps.unistra.fr/index.php/Jens_Gustedt ::

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Carlos O'Donell]

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.

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Jₑₙₛ Gustedt]

Hello Carlos,

On Tue, 27 May 2025 07:30:09 -0400, Carlos O'Donell wrote:

> > 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.

No, it can make *other* threads wait in a different queue. The
`FUTEX_WAIT` call is to put the current thread on wait. So calling
this equivalent is really far fetched.

Thanks
Jₑₙₛ


-- 
:: ICube :::::::::::::::::::::::::::::: deputy director ::
:: Université de Strasbourg :::::::::::::::::::::: ICPS ::
:: INRIA antenne de Strasbourg :::::::::::::::::: Camus ::
:: INRIA PIQ program Strasbourg :::::::::: piq.inria.fr ::
:: :::::::::::::::::::::::::::::::::::: ☎ +33 368854536 ::
:: https://icube-icps.unistra.fr/index.php/Jens_Gustedt ::

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4085 bytes --]

On Tue, May 27, 2025 at 07:30:09AM -0400, Carlos O'Donell wrote:
> 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.

Hi Carlos,

I disagree.  Let's see FUTEX_WAKE and FUTEX_REQUEUE side-by-side (to
ignore the check of FUTEX_CMP_REQUEUE).


	FUTEX_WAKE:

		long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAKE,
		             uint32_t val);

		Wakes up to 'val' waiters.


	FUTEX_REQUEUE:

		long syscall(SYS_futex, uint32_t *uaddr, FUTEX_REQUEUE,
		             uint32_t val,
		             uint32_t val2, uint32_t *uaddr2);

		Wakes up to 'val' waiters,
		and then requeues up to 'val2' more waiters to wait for
		something else.

If val2 is 0, then FUTEX_REQUEUE is equivalent to FUTEX_WAKE, as Jens
said.


Have a lovely day!
Alex

> 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.
> 
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Jₑₙₛ Gustedt]

Hello again,

On Tue, 27 May 2025 08:12:41 -0400, Carlos O'Donell wrote:

> > 	    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.

No, `val2 == 0` means that as many as specified in `val` are woken,
and that no task additionally is queued on `uaddr2`. So this is
definitively a wake operation.

The resulting text is then not completely correct, because it is
missing the tests for `val3` but at least is a bit closer to reality
than before.

Thanks
Jₑₙₛ


-- 
:: ICube :::::::::::::::::::::::::::::: deputy director ::
:: Université de Strasbourg :::::::::::::::::::::: ICPS ::
:: INRIA antenne de Strasbourg :::::::::::::::::: Camus ::
:: INRIA PIQ program Strasbourg :::::::::: piq.inria.fr ::
:: :::::::::::::::::::::::::::::::::::: ☎ +33 368854536 ::
:: https://icube-icps.unistra.fr/index.php/Jens_Gustedt ::

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3104 bytes --]

Hi Carlos,

On Tue, May 27, 2025 at 08:12:41AM -0400, Carlos O'Donell wrote:
> > > 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?

See my response to that one for more details.

> 
> > <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.

I'll show the patch with more context.  It's val2 which is 0, not val.

	$ git show -U7
	commit 74aa7971e5148f67d5def9977ed87cced638016a (HEAD -> contrib, alx/contrib)
	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
	@@ -497,15 +497,15 @@ .SS Futex operations
	 The limit value specified via
	 .I val2
	 is typically either 1 or
	 .BR INT_MAX .
	 (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 .)
	 .IP
	 The
	 .B FUTEX_CMP_REQUEUE
	 operation was added as a replacement for the earlier
	 .BR FUTEX_REQUEUE .
	 The difference is that the check of the value at
	 .I uaddr

> 
> 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.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Carlos O'Donell]

On 5/27/25 8:21 AM, Jₑₙₛ Gustedt wrote:
> Hello Carlos,
> 
> On Tue, 27 May 2025 07:30:09 -0400, Carlos O'Donell wrote:
> 
>>> 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.
> 
> No, it can make *other* threads wait in a different queue. The
> `FUTEX_WAIT` call is to put the current thread on wait. So calling
> this equivalent is really far fetched.

Sorry, I'm not sure what you're saying "No" to in this case.

I wrote that it can cause tasks to wait in a different queue, but you
wrote threads. Threads are really a userspace construct, while the
Linux kernel is really only aware tasks that have properties, so I
tend to call them tasks when speaking about the kernel tasks.

The text in question is parenthetical, and is correct for a val==0
API call, where zero waiters are woken, but for which up to val2
waiters are "moved" (atomic WAKE/WAIT into uaddr2).

While you call it "far fetched" is a parenthetical side comment
that is correct for the odd corner case of val==0?

-- 
Cheers,
Carlos.

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Carlos O'Donell]

On 5/27/25 8:23 AM, Alejandro Colomar wrote:
> On Tue, May 27, 2025 at 07:30:09AM -0400, Carlos O'Donell wrote:
>> 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.
> 
> Hi Carlos,
> 
> I disagree.  Let's see FUTEX_WAKE and FUTEX_REQUEUE side-by-side (to
> ignore the check of FUTEX_CMP_REQUEUE).
> 
> 
> 	FUTEX_WAKE:
> 
> 		long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAKE,
> 		             uint32_t val);
> 
> 		Wakes up to 'val' waiters.
> 
> 
> 	FUTEX_REQUEUE:
> 
> 		long syscall(SYS_futex, uint32_t *uaddr, FUTEX_REQUEUE,
> 		             uint32_t val,
> 		             uint32_t val2, uint32_t *uaddr2);
> 
> 		Wakes up to 'val' waiters,
> 		and then requeues up to 'val2' more waiters to wait for
> 		something else.
> 
> If val2 is 0, then FUTEX_REQUEUE is equivalent to FUTEX_WAKE, as Jens
> said.

I see the confusion.

The parenthetical does not clarify if it is talking about val or val2,
though they follow on from such comments.

I interpreted the parentheicals to carry on a set of comments about
val==0 and val2==1||INT_MAX.

I agree that if it is a parenthetical about val2 alone, then it *might*
be equivalent to FUTEX_WAKE, but it also might not be... and depends
on the value of val.

The clarification here should be about the value of val and val2 in the
parenthetical.

-- 
Cheers,
Carlos.

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Carlos O'Donell]

On 5/27/25 8:28 AM, Jₑₙₛ Gustedt wrote:
> Hello again,
> 
> On Tue, 27 May 2025 08:12:41 -0400, Carlos O'Donell wrote:
> 
>>> 	    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.
> 
> No, `val2 == 0` means that as many as specified in `val` are woken,
> and that no task additionally is queued on `uaddr2`. So this is
> definitively a wake operation.

I think we are talking past each other.

Since the parenthetical is not clear about val vs. val2, it can be
read in two different ways.

See my comments downthread about how to improve this.

-- 
Cheers,
Carlos.

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Carlos O'Donell]

On 5/27/25 8:28 AM, Alejandro Colomar wrote:
> Hi Carlos,
> 
> On Tue, May 27, 2025 at 08:12:41AM -0400, Carlos O'Donell wrote:
>>>> 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?
> 
> See my response to that one for more details.
> 
>>
>>> <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.
> 
> I'll show the patch with more context.  It's val2 which is 0, not val.
> 
> 	$ git show -U7
> 	commit 74aa7971e5148f67d5def9977ed87cced638016a (HEAD -> contrib, alx/contrib)
> 	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
> 	@@ -497,15 +497,15 @@ .SS Futex operations
> 	 The limit value specified via
> 	 .I val2
> 	 is typically either 1 or
> 	 .BR INT_MAX .
> 	 (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 .)

Suggest:

(Specifying val as INT_MAX is not useful, because it would make the
  FUTEX_CMP_REQUEUE  operation  equivalent  to  FUTEX_WAKE.)

Suggest:

(Specifying val2 as 0 is not useful, because it may make the
  FUTEX_CMP_REQUEUE operation equivalent to FUTEX_WAKE depending
  on val and val3.)

What do you think?


> 	 .IP
> 	 The
> 	 .B FUTEX_CMP_REQUEUE
> 	 operation was added as a replacement for the earlier
> 	 .BR FUTEX_REQUEUE .
> 	 The difference is that the check of the value at
> 	 .I uaddr
> 
>>
>> 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.
> 
> Have a lovely day!
> Alex
> 


-- 
Cheers,
Carlos.

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1007 bytes --]

Hi Carlos,

On Tue, May 27, 2025 at 08:37:16AM -0400, Carlos O'Donell wrote:
> Since the parenthetical is not clear about val vs. val2, it can be
> read in two different ways.

The entire paragraph is

            Typical  values to specify for val are 0 or 1.  (Specifying
            INT_MAX is not  useful,  because  it  would  make  the  FU‐
            TEX_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, be‐
            cause it would make the FUTEX_CMP_REQUEUE operation equiva‐
            lent to FUTEX_WAIT.)


There's a parenthetical after talking about val, and another one after
talking about val2.  I think the latter parenthetical unambiguously
refers to val2.  I would have written them as part of each sentence, to
make it even less ambiguous, though.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Carlos O'Donell]

On 5/27/25 8:51 AM, Alejandro Colomar wrote:
> Hi Carlos,
> 
> On Tue, May 27, 2025 at 08:37:16AM -0400, Carlos O'Donell wrote:
>> Since the parenthetical is not clear about val vs. val2, it can be
>> read in two different ways.
> 
> The entire paragraph is
> 
>              Typical  values to specify for val are 0 or 1.  (Specifying
>              INT_MAX is not  useful,  because  it  would  make  the  FU‐
>              TEX_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, be‐
>              cause it would make the FUTEX_CMP_REQUEUE operation equiva‐
>              lent to FUTEX_WAIT.)
> 
> 
> There's a parenthetical after talking about val, and another one after
> talking about val2.  I think the latter parenthetical unambiguously
> refers to val2.  I would have written them as part of each sentence, to
> make it even less ambiguous, though.

Just adding "val" and "val2" to the parenthenticals removes any confusion
if you are quickly skimming the text?

There is still the degenerate case of val==0 and val2==INT_MAX which is
equivalent to FUTEX_WAKE followed by an atomic FUTEX_WAIT since all
waiters move queues and no waiter is officially woken and allowed to
return to userspace?

-- 
Cheers,
Carlos.

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 688 bytes --]

Hi Carlos,

On Tue, May 27, 2025 at 08:42:27AM -0400, Carlos O'Donell wrote:
> 
> Suggest:
> 
> (Specifying val as INT_MAX is not useful, because it would make the
>  FUTEX_CMP_REQUEUE  operation  equivalent  to  FUTEX_WAKE.)
> 
> Suggest:
> 
> (Specifying val2 as 0 is not useful, because it may make the
>  FUTEX_CMP_REQUEUE operation equivalent to FUTEX_WAKE depending
>  on val and val3.)
> 
> What do you think?

The 'Specifying XXX as YYY' part looks good to me.  I'll apply a patch.
Thanks!

About the rest of the sentences (specifically the val3 part), I want to
see some more discussion first.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1866 bytes --]

On Tue, May 27, 2025 at 02:57:13PM +0200, Alejandro Colomar wrote:
> Hi Carlos,
> 
> On Tue, May 27, 2025 at 08:42:27AM -0400, Carlos O'Donell wrote:
> > 
> > Suggest:
> > 
> > (Specifying val as INT_MAX is not useful, because it would make the
> >  FUTEX_CMP_REQUEUE  operation  equivalent  to  FUTEX_WAKE.)
> > 
> > Suggest:
> > 
> > (Specifying val2 as 0 is not useful, because it may make the
> >  FUTEX_CMP_REQUEUE operation equivalent to FUTEX_WAKE depending
> >  on val and val3.)
> > 
> > What do you think?
> 
> The 'Specifying XXX as YYY' part looks good to me.  I'll apply a patch.
> Thanks!

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=0ee8ef52fdb32cd1a54a781a1987291e22f010b1>

	commit 0ee8ef52fdb32cd1a54a781a1987291e22f010b1 (HEAD -> contrib, alx/contrib)
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   Tue May 27 14:58:09 2025 +0200

	    man/man2/futex.2: wfix
	    
	    Suggested-by: Carlos O'Donell <carlos@redhat.com>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man2/futex.2 b/man/man2/futex.2
	index 9a15a0fdb..a5c24fe8a 100644
	--- a/man/man2/futex.2
	+++ b/man/man2/futex.2
	@@ -489,8 +489,11 @@ .SS Futex operations
	 .I val
	 are 0 or 1.
	 (Specifying
	+.I val
	+as
	 .B INT_MAX
	-is not useful, because it would make the
	+is not useful,
	+because it would make the
	 .B FUTEX_CMP_REQUEUE
	 operation equivalent to
	 .BR FUTEX_WAKE .)
	@@ -498,7 +501,10 @@ .SS Futex operations
	 .I val2
	 is typically either 1 or
	 .BR INT_MAX .
	-(Specifying the argument as 0 is not useful, because it would make the
	+(Specifying
	+.I val2
	+as 0 is not useful,
	+because it would make the
	 .B FUTEX_CMP_REQUEUE
	 operation equivalent to
	 .BR FUTEX_WAKE .)


-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Jₑₙₛ Gustedt]

Hello Carlos,

On Tue, 27 May 2025 08:42:27 -0400, Carlos O'Donell wrote:

> Suggest:
> 
> (Specifying val as INT_MAX is not useful, because it would make the
>   FUTEX_CMP_REQUEUE  operation  equivalent  to  FUTEX_WAKE.)

That is not true because `val3` is checked for the first and not the
second, so they are not equivalent. And indeed `val` as `INT_MAX` is
usefull, because it provides a wake up of everybody with an additional
check of `val3`.

> Suggest:
> 
> (Specifying val2 as 0 is not useful, because it may make the
>   FUTEX_CMP_REQUEUE operation equivalent to FUTEX_WAKE depending
>   on val and val3.)

I think that specifying `val2` as `0` is in fact useful because it
provides a wake operation that additionally checks for `val3`. (and
does no requeing)


Thanks
Jₑₙₛ


-- 
:: ICube :::::::::::::::::::::::::::::: deputy director ::
:: Université de Strasbourg :::::::::::::::::::::: ICPS ::
:: INRIA antenne de Strasbourg :::::::::::::::::: Camus ::
:: INRIA PIQ program Strasbourg :::::::::: piq.inria.fr ::
:: :::::::::::::::::::::::::::::::::::: ☎ +33 368854536 ::
:: https://icube-icps.unistra.fr/index.php/Jens_Gustedt ::

Re: bug in futex.2, FUTEX_CMP_REQUEUE

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 878 bytes --]

Hi Jens,

On Tue, May 27, 2025 at 02:01:13PM +0200, Alejandro Colomar wrote:
> I'll wait a little bit before doing anything to see if someone else
> wants to chime in.  I never used futex(2), so can't comment much.  It
> sounds more or less reasonable.
> 
> In the meantime, I see some other things that need updates regarding
> futex(2), so I'll work on that (e.g., the futex_requeue() system call).

I've refactored this page into smaller pages for each operation.
I've pushed these changes to my server:

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/log/?h=contrib&id=f0114c4e07162ecd13fd7d442aa14fd9e19c9732>

And will push them to <kernel.org> in the following days.
Now, the documentation about FUTEX_CMP_REQUEUE will be in
FUTEX_CMP_REQUEUE(2const).


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]