bug in futex.2, FUTEX_CMP_REQUEUE

DISCUSSION Jₑₙₛ Gustedt 3 participants 18 messages May 27, 2025 – May 29, 2025 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Jₑₙₛ Gustedt

author

2025-05-27 09:54 UTC #0 lore raw

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

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ₑₙₛ

Signature · 6 lines

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

Carlos O'Donell

2025-05-27 11:30 UTC #1 lore raw

Quoted 18 lines · 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.

Quoted 4 lines

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.

Quoted 4 lines

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.

Quoted 14 lines

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.

Quoted 8 lines

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?

Signature · 2 lines

Cheers,
Carlos.

Jₑₙₛ Gustedt

author

2025-05-27 12:21 UTC #2 lore raw

Hello Carlos,

Quoted 11 lines · Carlos O'Donell

Quoted 5 lines
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ₑₙₛ

Signature · 6 lines

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

Carlos O'Donell

2025-05-27 12:29 UTC #3 lore raw

Quoted 12 lines · Jₑₙₛ Gustedt

Hello Carlos,
Quoted 8 lines · Carlos O'Donell
Quoted 5 lines
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.

Quoted 7 lines

Quoted 3 lines
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?

Signature · 2 lines

Cheers,
Carlos.

Alejandro Colomar

maintainer

2025-05-27 12:23 UTC #4 lore raw

In reply to Carlos O'Donell

Quoted 19 lines · Carlos O'Donell

Quoted 18 lines · 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.

Quoted 6 lines

Quoted 4 lines
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

Quoted 51 lines

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.
Quoted 4 lines
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.
Quoted 14 lines
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.
Quoted 8 lines
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?
Signature · 2 lines
Cheers,
Carlos.

Signature · 1 line

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

Carlos O'Donell

2025-05-27 12:35 UTC #5 lore raw

Quoted 47 lines · Alejandro Colomar

Quoted 19 lines · Carlos O'Donell
Quoted 18 lines · 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.
Quoted 6 lines
Quoted 4 lines
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);

Quoted 6 lines

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.

Signature · 2 lines

Cheers,
Carlos.

Alejandro Colomar

maintainer

2025-05-27 12:01 UTC #6 lore raw

In reply to Jₑₙₛ Gustedt

[Added a few people to CC]

Hi Jens,

Quoted 18 lines · 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.

Quoted 4 lines

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

Quoted 3 lines

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 <[email protected]>
	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 <[email protected]>
	    Signed-off-by: Alejandro Colomar <[email protected]>

	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

Quoted 3 lines

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.

Quoted 14 lines

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.

Quoted 8 lines

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

Quoted 11 lines

Thanks
Jₑₙₛ

Signature · 6 lines

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

Signature · 1 line

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

Carlos O'Donell

2025-05-27 12:12 UTC #7 lore raw

Quoted 23 lines · Alejandro Colomar

[Added a few people to CC]
Hi Jens,
Quoted 18 lines · 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.

Quoted 7 lines

Quoted 4 lines
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?

Quoted 15 lines

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

	commit 74aa7971e5148f67d5def9977ed87cced638016a
	Author: Alejandro Colomar <[email protected]>
	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 <[email protected]>
	    Signed-off-by: Alejandro Colomar <[email protected]>

	diff --git a/man/man2/futex.2 b/man/man2/futex.2
	index 128612ee1..9a15a0fdb 100644

Quoted 8 lines

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

Signature · 2 lines

Cheers,
Carlos.

Alejandro Colomar

maintainer

2025-05-27 12:28 UTC #8 lore raw

Hi Carlos,

Quoted 9 lines · Carlos O'Donell

Quoted 7 lines
Quoted 4 lines
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.

Quoted 25 lines

Quoted 16 lines

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

	commit 74aa7971e5148f67d5def9977ed87cced638016a
	Author: Alejandro Colomar <[email protected]>
	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 <[email protected]>
	    Signed-off-by: Alejandro Colomar <[email protected]>

	diff --git a/man/man2/futex.2 b/man/man2/futex.2
	index 128612ee1..9a15a0fdb 100644

Quoted 8 lines

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

Quoted 3 lines

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 <[email protected]>
	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 <[email protected]>
	    Signed-off-by: Alejandro Colomar <[email protected]>

	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

Quoted 3 lines

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

Signature · 1 line

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

Carlos O'Donell

2025-05-27 12:42 UTC #9 lore raw

Quoted 64 lines · Alejandro Colomar

Hi Carlos,
Quoted 9 lines · Carlos O'Donell
Quoted 7 lines
Quoted 4 lines
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.
Quoted 25 lines
Quoted 16 lines
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=74aa7971e5148f67d5def9977ed87cced638016a>
	commit 74aa7971e5148f67d5def9977ed87cced638016a
	Author: Alejandro Colomar <[email protected]>
	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 <[email protected]>
	    Signed-off-by: Alejandro Colomar <[email protected]>

	diff --git a/man/man2/futex.2 b/man/man2/futex.2
	index 128612ee1..9a15a0fdb 100644
Quoted 8 lines
	--- 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 .)
Quoted 3 lines
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 <[email protected]>
	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 <[email protected]>
	    Signed-off-by: Alejandro Colomar <[email protected]>

	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

Quoted 8 lines

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

Quoted 15 lines

.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
Quoted 3 lines
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

Signature · 2 lines

Cheers,
Carlos.

Alejandro Colomar

maintainer

2025-05-27 12:57 UTC #10 lore raw

Hi Carlos,

Quoted 6 lines · Carlos O'Donell

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

Quoted 7 lines

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

Signature · 1 line

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

Alejandro Colomar

maintainer

2025-05-27 12:59 UTC #11 lore raw

Quoted 11 lines · Alejandro Colomar

Hi Carlos,
Quoted 8 lines · Carlos O'Donell
Suggest:
(Specifying val as INT_MAX is not useful, because it would make the
FUTEX_CMP_REQUEUE operation equivalent to FUTEX_WAKE.)
Suggest:

Quoted 8 lines

Quoted 5 lines
(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 <[email protected]>
Date: Tue May 27 14:58:09 2025 +0200

man/man2/futex.2: wfix

Signed-off-by Alejandro Colomar <[email protected]>

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

Signature · 1 line

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

Jₑₙₛ Gustedt

author

2025-05-27 13:07 UTC #12 lore raw

In reply to Carlos O'Donell

Hello Carlos,

Quoted 4 lines · Carlos O'Donell

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.

Quoted 5 lines

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ₑₙₛ

Signature · 6 lines

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

Jₑₙₛ Gustedt

author

2025-05-27 12:29 UTC #13 lore raw

In reply to Carlos O'Donell

Hello again,

Quoted 17 lines · Carlos O'Donell

Quoted 6 lines
	    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 <[email protected]>
Signed-off-by Alejandro Colomar <[email protected]>
Quoted 10 lines
	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 .)  

Quoted 3 lines

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ₑₙₛ

Signature · 6 lines

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

Carlos O'Donell

2025-05-27 12:37 UTC #14 lore raw

Quoted 21 lines · Jₑₙₛ Gustedt

Hello again,
Quoted 17 lines · Carlos O'Donell
Quoted 16 lines
	    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 <[email protected]>
Signed-off-by Alejandro Colomar <[email protected]>
	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 .)

Quoted 7 lines

Quoted 3 lines
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.

Signature · 2 lines

Cheers,
Carlos.

Alejandro Colomar

maintainer

2025-05-27 12:51 UTC #15 lore raw

Hi Carlos,

Quoted 2 lines · Carlos O'Donell

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

Signature · 1 line

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

Carlos O'Donell

2025-05-27 12:54 UTC #16 lore raw

Quoted 17 lines · Alejandro Colomar

Hi Carlos,
Quoted 2 lines · Carlos O'Donell
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.)

Quoted 4 lines

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?

Signature · 2 lines

Cheers,
Carlos.

Alejandro Colomar

maintainer

2025-05-29 23:35 UTC #17 lore raw

In reply to Alejandro Colomar

Hi Jens,

Quoted 6 lines · Alejandro Colomar

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

Signature · 1 line

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