bug in futex.2, FUTEX_CMP_REQUEUE

["Jₑₙₛ Gustedt" <jens.gustedt@inria.fr>]

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