Re: futex(3) man page, final draft for pre-release review

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

Hello Torvald,

On 12/15/2015 04:34 PM, Torvald Riegel wrote:
> On Tue, 2015-12-15 at 14:43 +0100, Michael Kerrisk (man-pages) wrote:
>> Hello all,
>>
>> After much too long a time, the revised futex man page *will*
>> go out in the next man pages release (it has been merged
>> into master).
>>
>> There are various places where the page could still be improved,
>> but it is much better (and more than 5 times longer) than the
>> existing page.
> 
> This looks good to me; I just saw minor things (see below).  Thank you
> for all the work you put into this (and to everybody who contributed)!

Hey Torvald, you were one of the biggest contributors, so, thanks!

>>        When executing a futex operation that requests to block a thread,
>>        the kernel will block only if the futex word has the  value  that
>>        the  calling  thread  supplied  (as  one  of the arguments of the
>>        futex() call) as the expected value of the futex word.  The load‐
>>        ing  of the futex word's value, the comparison of that value with
>>        the expected value, and the actual blocking  will  happen  atomi‐
>>
>> FIXME: for next line, it would be good to have an explanation of
>> "totally ordered" somewhere around here.
>>
>>        cally  and totally ordered with respect to concurrently executing
>>        futex operations on the same futex word.  Thus, the futex word is
>>        used to connect the synchronization in user space with the imple‐
>>        mentation of blocking by the kernel.  Analogously  to  an  atomic
>>        compare-and-exchange  operation  that  potentially changes shared
>>        memory, blocking via a futex is an atomic compare-and-block oper‐
>>        ation.
> 
> Maybe -- should we just say that it refers to the mathematical notion of
> a total order (or, technically, a strict total order in this case)?

I added a sentence along those lines.

> Though I would hope that everyone using futexes is roughly aware of the
> differences between partial and total orders.

>>        FUTEX_TRYLOCK_PI (since Linux 2.6.18)
>>               This operation tries to acquire the futex at uaddr.  It is
> 
> s/futex/lock/ to make it consistent with FUTEX_LOCK.

Done.

>>               invoked when a user-space atomic acquire did  not  succeed
>>               because the futex word was not 0.
>>
>>
>> FIXME(Next sentence) The wording "The trylock in kernel" below 
>> needs clarification. Suggestions?
>>
>>               The trylock in kernel might succeed because the futex word
>>               contains     stale     state     (FUTEX_WAITERS     and/or
>>               FUTEX_OWNER_DIED).   This can happen when the owner of the
>>               futex died.  User space cannot handle this condition in  a
>>               race-free  manner,  but  the  kernel  can  fix this up and
>>               acquire the futex.
>>
>>               The uaddr2, val, timeout, and val3 arguments are ignored.
> 
> What about "The acquisition of the lock might suceed if performed by the
> kernel in cases when the futex word contains stale state...".

Sounds good to me. Changed.

>>        FUTEX_WAIT_REQUEUE_PI (since Linux 2.6.31)
>>               Wait  on  a  non-PI  futex  at  uaddr  and  potentially be
>>               requeued (via a FUTEX_CMP_REQUEUE_PI operation in  another
>>               task)  onto  a  PI futex at uaddr2.  The wait operation on
>>               uaddr is the same as for FUTEX_WAIT.
>>
>>               The waiter can be removed from the wait on  uaddr  without
>>               requeueing on uaddr2 via a FUTEX_WAKE operation in another
>>               task.  In this case, the  FUTEX_WAIT_REQUEUE_PI  operation
>>               returns with the error EWOULDBLOCK.
> 
> This should be EAGAIN, I suppose, or the enumeration of errors should
> include EWOULDBLOCK.

Changed. BTW, under ERRORS there is already this text:

              Note:  on Linux, the symbolic names EAGAIN and EWOULDBLOCK
              (both of which appear in different  parts  of  the  kernel
              futex code) have the same value.

Thanks for the comments, Torvald!

Cheers,

Michael

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