From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S1753341AbbCaUhV (ORCPT <rfc822;w@1wt.eu>);
	Tue, 31 Mar 2015 16:37:21 -0400
Received: from cantor2.suse.de ([195.135.220.15]:38911 "EHLO mx2.suse.de"
	rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP
	id S1752215AbbCaUhQ (ORCPT <rfc822;linux-kernel@vger.kernel.org>);
	Tue, 31 Mar 2015 16:37:16 -0400
Message-ID: <1427834205.20009.19.camel@stgolabs.net>
Subject: Re: Revised futex(2) man page for review
From: Davidlohr Bueso <dave@stgolabs.net>
To: Peter Zijlstra <peterz@infradead.org>
Cc: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>,
        Thomas Gleixner <tglx@linutronix.de>,
        Darren Hart <dvhart@linux.intel.com>,
        "Carlos O'Donell" <carlos@redhat.com>, Ingo Molnar <mingo@elte.hu>,
        Jakub Jelinek <jakub@redhat.com>,
        "linux-man@vger.kernel.org" <linux-man@vger.kernel.org>,
        lkml <linux-kernel@vger.kernel.org>, Arnd Bergmann <arnd@arndb.de>,
        Steven Rostedt <rostedt@goodmis.org>,
        Linux API <linux-api@vger.kernel.org>,
        Torvald Riegel <triegel@redhat.com>,
        Roland McGrath <roland@hack.frob.com>,
        Darren Hart <dvhart@infradead.org>, Anton Blanchard <anton@samba.org>,
        Eric Dumazet <edumazet@google.com>,
        bill o gallmeister <bgallmeister@gmail.com>,
        Jan Kiszka <jan.kiszka@siemens.com>, Daniel Wagner <wagi@monom.org>,
        Rich Felker <dalias@libc.org>, Andy Lutomirski <luto@amacapital.net>,
        bert hubert <bert.hubert@netherlabs.nl>,
        Rusty Russell <rusty@rustcorp.com.au>,
        Heinrich Schuchardt <xypron.glpk@gmx.de>
Date: Tue, 31 Mar 2015 13:36:45 -0700
In-Reply-To: <20150328120337.GB32047@worktop.ger.corp.intel.com>
References: <55166C01.7000803@gmail.com>
	 <20150328114725.GJ27490@worktop.programming.kicks-ass.net>
	 <20150328120337.GB32047@worktop.ger.corp.intel.com>
Content-Type: text/plain; charset="UTF-8"
X-Mailer: Evolution 3.12.9 
Mime-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Sat, 2015-03-28 at 13:03 +0100, Peter Zijlstra wrote:
> >               If the timeout argument is non-NULL, its contents specify a rel‐
> >               ative   timeout   for   the  wait,  measured  according  to  the
> >               CLOCK_MONOTONIC clock.  (This interval will be rounded up to the
> >               system clock granularity, and kernel scheduling delays mean that
> >               the blocking interval may overrun by a small amount.)  If  time‐
> >               out is NULL, the call blocks indefinitely.
> 
> Would it not be better to only state that the wait will not return
> before the timeout -- unless woken -- and not bother with clock
> granularity and scheduling delays?

Yeah, similarly we also have this:

     FUTEX_PRIVATE_FLAG (since Linux 2.6.22)
              This option bit can be employed with all futex  operations.   It
              tells  the  kernel  that  the  futex  is process-private and not
              shared with another process (i.e., it is  only  being  used  for
              synchronization  between  threads  of  the  same process).  This
              allows the kernel to choose the fast  path  for  validating  the
              user-space address and avoids expensive VMA lookups, taking ref‐
              erence counts on file backing store, and so on.

This to me reads a bit too much into the kernel (fastpath, refcnt,
vmas). Why not just mention that it avoids overhead in the kernel or
something? I don't recall any manpage mentioning such details, but I
could be wrong. In any case its a nit, the whole doc is pretty good and
I hope you can merge it soon and then just increment ;)

Thanks,
Davidlohr