From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752433AbbG0LLL (ORCPT ); Mon, 27 Jul 2015 07:11:11 -0400 Received: from mail-wi0-f169.google.com ([209.85.212.169]:37224 "EHLO mail-wi0-f169.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752247AbbG0LLH (ORCPT ); Mon, 27 Jul 2015 07:11:07 -0400 Message-ID: <55B611BF.8040908@gmail.com> Date: Mon, 27 Jul 2015 13:10:55 +0200 From: "Michael Kerrisk (man-pages)" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.7.0 MIME-Version: 1.0 To: Peter Zijlstra CC: mtk.manpages@gmail.com, Thomas Gleixner , Darren Hart , "Carlos O'Donell" , Ingo Molnar , Jakub Jelinek , "linux-man@vger.kernel.org" , lkml , Davidlohr Bueso , Arnd Bergmann , Steven Rostedt , Linux API , Torvald Riegel , Roland McGrath , Darren Hart , Anton Blanchard , Eric Dumazet , bill o gallmeister , Jan Kiszka , Daniel Wagner , Rich Felker , Andy Lutomirski , bert hubert , Rusty Russell , Heinrich Schuchardt Subject: Re: Revised futex(2) man page for review References: <55166C01.7000803@gmail.com> <20150328114725.GJ27490@worktop.programming.kicks-ass.net> <20150328120337.GB32047@worktop.ger.corp.intel.com> In-Reply-To: <20150328120337.GB32047@worktop.ger.corp.intel.com> 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 Hi Peter, On 03/28/2015 01:03 PM, Peter Zijlstra wrote: > 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? Many of the pages that talk about system calls that have timeouts carry similar language, since people often have confusions about what time timeout (e.g., that it's an upper limit, not a minimum; or that it's precise to some very small granularity). Why do you think the language here is a problem? Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/