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

On 5/27/25 5:53 AM, Jₑₙₛ Gustedt wrote:

quoted

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.

quoted

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

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