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 S1753450AbbC1MEA (ORCPT <rfc822;w@1wt.eu>);
	Sat, 28 Mar 2015 08:04:00 -0400
Received: from bombadil.infradead.org ([198.137.202.9]:42475 "EHLO
	bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
	with ESMTP id S1752788AbbC1MD4 (ORCPT
	<rfc822;linux-kernel@vger.kernel.org>);
	Sat, 28 Mar 2015 08:03:56 -0400
Date: Sat, 28 Mar 2015 13:03:37 +0100
From: Peter Zijlstra <peterz@infradead.org>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Cc: 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>,
        Davidlohr Bueso <dave@stgolabs.net>, 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>
Subject: Re: Revised futex(2) man page for review
Message-ID: <20150328120337.GB32047@worktop.ger.corp.intel.com>
References: <55166C01.7000803@gmail.com>
 <20150328114725.GJ27490@worktop.programming.kicks-ass.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20150328114725.GJ27490@worktop.programming.kicks-ass.net>
User-Agent: Mutt/1.5.22.1 (2013-10-16)
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Sat, Mar 28, 2015 at 12:47:25PM +0100, Peter Zijlstra wrote:
>        FUTEX_WAIT (since Linux 2.6.0)
>               This operation tests that the value at the futex word pointed to
>               by the address uaddr still contains the expected value val,  and
>               if  so,  then sleeps awaiting FUTEX_WAKE on the futex word.  The
>               load of the value of the futex word is an atomic  memory  access
>               (i.e.,  using  atomic  machine  instructions  of  the respective
>               architecture).  This load,  the  comparison  with  the  expected
>               value,  and  starting  to  sleep  are  performed  atomically and
>               totally ordered with respect to other futex  operations  on  the
>               same  futex  word.  If the thread starts to sleep, it is consid‐
>               ered a waiter on this futex word.  If the futex value  does  not
>               match  val,  then  the  call  fails  immediately  with the error
>               EAGAIN.
> 
>               The purpose of the comparison with the expected value is to pre‐
>               vent  lost  wake-ups: If another thread changed the value of the
>               futex word after the calling thread decided to  block  based  on
>               the  prior  value, and if the other thread executed a FUTEX_WAKE
>               operation (or similar wake-up) after the value change and before
>               this  FUTEX_WAIT  operation,  then  the  latter will observe the
>               value change and will not start to sleep.
> 
>               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?