Date:	Tue, 15 Dec 2015 17:02:45 +0100
From:	"Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
To:	Torvald Riegel <triegel@...hat.com>
CC:	mtk.manpages@...il.com, Thomas Gleixner <tglx@...utronix.de>,
	Darren Hart <dvhart@...radead.org>,
	lkml <linux-kernel@...r.kernel.org>,
	libc-alpha <libc-alpha@...rceware.org>,
	linux-man <linux-man@...r.kernel.org>,
	Carlos O'Donell <carlos@...hat.com>,
	Roland McGrath <roland@...k.frob.com>,
	Davidlohr Bueso <dave@...olabs.net>,
	Jakub Jelinek <jakub@...hat.com>, Ingo Molnar <mingo@...e.hu>,
	bill o gallmeister <bgallmeister@...il.com>,
	bert hubert <bert.hubert@...herlabs.nl>,
	Jan Kiszka <jan.kiszka@...mens.com>,
	Eric Dumazet <edumazet@...gle.com>,
	Arnd Bergmann <arnd@...db.de>,
	Rusty Russell <rusty@...tcorp.com.au>,
	Heinrich Schuchardt <xypron.glpk@....de>,
	Andy Lutomirski <luto@...capital.net>,
	Daniel Wagner <wagi@...om.org>,
	Anton Blanchard <anton@...ba.org>,
	Steven Rostedt <rostedt@...dmis.org>,
	Rich Felker <dalias@...c.org>,
	Jonathan Wakely <jwakely@...hat.com>,
	Mike Frysinger <vapier@...too.org>
Subject: Re: futex(3) man page, final draft for pre-release review

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@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Powered by blists - more mailing lists