This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: futex(3) man page, final draft for pre-release review
- From: Torvald Riegel <triegel at redhat dot com>
- To: "Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>
- Cc: Darren Hart <dvhart at infradead dot org>, Thomas Gleixner <tglx at linutronix dot de>, lkml <linux-kernel at vger dot kernel dot org>, libc-alpha <libc-alpha at sourceware dot org>, linux-man <linux-man at vger dot kernel dot org>, "Carlos O'Donell" <carlos at redhat dot com>, Roland McGrath <roland at hack dot frob dot com>, Davidlohr Bueso <dave at stgolabs dot net>, Jakub Jelinek <jakub at redhat dot com>, Ingo Molnar <mingo at elte dot hu>, bill o gallmeister <bgallmeister at gmail dot com>, bert hubert <bert dot hubert at netherlabs dot nl>, Jan Kiszka <jan dot kiszka at siemens dot com>, Eric Dumazet <edumazet at google dot com>, Arnd Bergmann <arnd at arndb dot de>, Rusty Russell <rusty at rustcorp dot com dot au>, Heinrich Schuchardt <xypron dot glpk at gmx dot de>, Andy Lutomirski <luto at amacapital dot net>, Daniel Wagner <wagi at monom dot org>, Anton Blanchard <anton at samba dot org>, Steven Rostedt <rostedt at goodmis dot org>, Rich Felker <dalias at libc dot org>, Jonathan Wakely <jwakely at redhat dot com>, Mike Frysinger <vapier at gentoo dot org>
- Date: Fri, 18 Dec 2015 12:11:01 +0100
- Subject: Re: futex(3) man page, final draft for pre-release review
- Authentication-results: sourceware.org; auth=none
- References: <56701916 dot 4090203 at gmail dot com> <20151215211816 dot GR11972 at malice dot jf dot intel dot com> <5671891E dot 404 at gmail dot com>
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).