Re: Revised futex(2) man page for review

[Davidlohr Bueso <dave@stgolabs.net>]

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