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: "Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>
- To: Torvald Riegel <triegel at redhat dot com>
- Cc: mtk dot manpages at gmail dot com, 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: Sat, 19 Dec 2015 07:54:24 +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> <1450437061 dot 26597 dot 45 dot camel at localhost dot localdomain>
On 12/18/2015 12:11 PM, Torvald Riegel wrote:
> 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" :)
Sigh :-). Okay--removed.
> 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).
And I'd be really happy to see such an explanation land in the page.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/