Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1292279 > unrolled thread

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

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: futex(3) man page, final draft for pre-release review Torvald Riegel <triegel@redhat.com> - 2015-12-15 16:40 +0100
    Re: futex(3) man page, final draft for pre-release review "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2015-12-15 17:10 +0100

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

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

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

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

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

Torvald

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [next] | [standalone]

#1292316

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/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web