Message-ID: <1450437061.26597.45.camel@localhost.localdomain>
Subject: Re: futex(3) man page, final draft for pre-release review
From: Torvald Riegel <triegel@redhat.com>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: Darren Hart <dvhart@infradead.org>, Thomas Gleixner <tglx@linutronix.de>,
        lkml <linux-kernel@vger.kernel.org>,
        libc-alpha <libc-alpha@sourceware.org>,
        linux-man <linux-man@vger.kernel.org>,
        "Carlos O'Donell" <carlos@redhat.com>,
        Roland McGrath <roland@hack.frob.com>,
        Davidlohr Bueso <dave@stgolabs.net>, Jakub Jelinek <jakub@redhat.com>,
        Ingo Molnar <mingo@elte.hu>,
        bill o gallmeister <bgallmeister@gmail.com>,
        bert hubert <bert.hubert@netherlabs.nl>,
        Jan Kiszka <jan.kiszka@siemens.com>,
        Eric Dumazet <edumazet@google.com>, Arnd Bergmann <arnd@arndb.de>,
        Rusty Russell <rusty@rustcorp.com.au>,
        Heinrich Schuchardt <xypron.glpk@gmx.de>,
        Andy Lutomirski <luto@amacapital.net>, Daniel Wagner <wagi@monom.org>,
        Anton Blanchard <anton@samba.org>,
        Steven Rostedt <rostedt@goodmis.org>, Rich Felker <dalias@libc.org>,
        Jonathan Wakely <jwakely@redhat.com>,
        Mike Frysinger <vapier@gentoo.org>
Date: Fri, 18 Dec 2015 12:11:01 +0100
In-Reply-To: <5671891E.404@gmail.com>
References: <56701916.4090203@gmail.com>
	 <20151215211816.GR11972@malice.jf.intel.com> <5671891E.404@gmail.com>
Content-Type: text/plain; charset="UTF-8"
Mime-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 2167
Lines: 43

On Wed, 2015-12-16 at 16:54 +0100, Michael Kerrisk (man-pages) wrote:
> Hello Darren,
> 
> On 12/15/2015 10:18 PM, Darren Hart wrote:
> > On Tue, Dec 15, 2015 at 02:43:50PM +0100, Michael Kerrisk (man-pages) wrote:
> 
> [...]
> 
> >>        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
> > 
> > Totally ordered with respect futex operations refers to semantics of the
> > ACQUIRE/RELEASE operations and how they impact ordering of memory reads and
> > writes. The kernel futex operations are protected by spinlocks, which ensure
> > that that all operations are serialized with respect to one another.
> > 
> > This is a lot to attempt to define in this document. Perhaps a reference to
> > linux/Documentation/memory-barriers.txt as a footnote would be sufficient? Or
> > perhaps for this manual, "serialized" would be sufficient, with a footnote
> > regarding "totally ordered" and a pointer to the memory-barrier documentation?
> 
> I think I'll just settle for writing serialized in the man page, and be 
> done with it :-).

I'd prefer if you'd not just use "serialized" :)  Eventually, I'd prefer
if we can explain the semantics for the user in terms of the terminology
and semantics of the memory model of the programming language that users
will likely use to call futex ops (ie, C11 / C++11).

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