Re: Revised futex(2) man page for review

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Peter,

On 03/28/2015 01:03 PM, Peter Zijlstra wrote:
> On Sat, Mar 28, 2015 at 12:47:25PM +0100, Peter Zijlstra wrote:
>>        FUTEX_WAIT (since Linux 2.6.0)
>>               This operation tests that the value at the futex word pointed to
>>               by the address uaddr still contains the expected value val,  and
>>               if  so,  then sleeps awaiting FUTEX_WAKE on the futex word.  The
>>               load of the value of the futex word is an atomic  memory  access
>>               (i.e.,  using  atomic  machine  instructions  of  the respective
>>               architecture).  This load,  the  comparison  with  the  expected
>>               value,  and  starting  to  sleep  are  performed  atomically and
>>               totally ordered with respect to other futex  operations  on  the
>>               same  futex  word.  If the thread starts to sleep, it is consid‐
>>               ered a waiter on this futex word.  If the futex value  does  not
>>               match  val,  then  the  call  fails  immediately  with the error
>>               EAGAIN.
>>
>>               The purpose of the comparison with the expected value is to pre‐
>>               vent  lost  wake-ups: If another thread changed the value of the
>>               futex word after the calling thread decided to  block  based  on
>>               the  prior  value, and if the other thread executed a FUTEX_WAKE
>>               operation (or similar wake-up) after the value change and before
>>               this  FUTEX_WAIT  operation,  then  the  latter will observe the
>>               value change and will not start to sleep.
>>
>>               If the timeout argument is non-NULL, its contents specify a rel‐
>>               ative   timeout   for   the  wait,  measured  according  to  the
>>               CLOCK_MONOTONIC clock.  (This interval will be rounded up to the
>>               system clock granularity, and kernel scheduling delays mean that
>>               the blocking interval may overrun by a small amount.)  If  time‐
>>               out is NULL, the call blocks indefinitely.
> 
> Would it not be better to only state that the wait will not return
> before the timeout -- unless woken -- and not bother with clock
> granularity and scheduling delays?

Many of the pages that talk about system calls that have timeouts
carry similar language, since people often have confusions about what time
timeout (e.g., that it's an upper limit, not a minimum; or that it's precise
to some very small granularity). Why do you think the language here is a
problem?

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/