From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932777AbbLRPi7 (ORCPT ); Fri, 18 Dec 2015 10:38:59 -0500 Received: from mx1.redhat.com ([209.132.183.28]:33534 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754170AbbLRPeI (ORCPT ); Fri, 18 Dec 2015 10:34:08 -0500 Date: Fri, 18 Dec 2015 15:34:02 +0000 From: Jonathan Wakely To: Torvald Riegel Cc: "Michael Kerrisk (man-pages)" , 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 , Mike Frysinger Subject: Re: futex(3) man page, final draft for pre-release review Message-ID: <20151218153402.GV5356@redhat.com> References: <56701916.4090203@gmail.com> <20151215211816.GR11972@malice.jf.intel.com> <5671891E.404@gmail.com> <1450437061.26597.45.camel@localhost.localdomain> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <1450437061.26597.45.camel@localhost.localdomain> X-Clacks-Overhead: GNU Terry Pratchett User-Agent: Mutt/1.5.24 (2015-08-30) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 18/12/15 12:11 +0100, 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" :) 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). FWIW a couple of uses of "serialized" were replaced in the C++11 final draft due to comments pointing out that term is not defined in the standard, see http://wg21.link/lwg1494 and http://wg21.link/lwg1504 That's not quite the same, because an ISO standard is supposed to define all terms it uses, even for something like "serialized" where the meaning is commonly understood by those in the field. But I do like Torvald's suggestion to describe the semantics in similar terms to C11, because that's the user-space model that non-kernel folks (like me) are more likely to be familiar with. Overall I like the new page a lot, I found it clear and readable. Nice work.