Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932366AbbLSGye (ORCPT ); Sat, 19 Dec 2015 01:54:34 -0500 Received: from mail-wm0-f41.google.com ([74.125.82.41]:37602 "EHLO mail-wm0-f41.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752619AbbLSGyc (ORCPT ); Sat, 19 Dec 2015 01:54:32 -0500 Subject: Re: futex(3) man page, final draft for pre-release review To: Torvald Riegel References: <56701916.4090203@gmail.com> <20151215211816.GR11972@malice.jf.intel.com> <5671891E.404@gmail.com> <1450437061.26597.45.camel@localhost.localdomain> Cc: mtk.manpages@gmail.com, Darren Hart , Thomas Gleixner , lkml , libc-alpha , linux-man , "Carlos O'Donell" , Roland McGrath , Davidlohr Bueso , Jakub Jelinek , Ingo Molnar , bill o gallmeister , bert hubert , Jan Kiszka , Eric Dumazet , Arnd Bergmann , Rusty Russell , Heinrich Schuchardt , Andy Lutomirski , Daniel Wagner , Anton Blanchard , Steven Rostedt , Rich Felker , Jonathan Wakely , Mike Frysinger From: "Michael Kerrisk (man-pages)" X-Enigmail-Draft-Status: N1110 Message-ID: <5674FF20.9030609@gmail.com> Date: Sat, 19 Dec 2015 07:54:24 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.4.0 MIME-Version: 1.0 In-Reply-To: <1450437061.26597.45.camel@localhost.localdomain> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2499 Lines: 60 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/ -- 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/