lkml.org 
[lkml]   [2015]   [Jul]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: Revised futex(2) man page for review
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/


\
 
 \ /
  Last update: 2015-07-27 13:21    [W:0.210 / U:0.460 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site