Re: Next round: revised futex(2) man page for review

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

On 07/29/2015 06:21 AM, Darren Hart wrote:
> On Tue, Jul 28, 2015 at 09:11:41PM -0700, Darren Hart wrote:
>> On Tue, Jul 28, 2015 at 10:23:51PM +0200, Thomas Gleixner wrote:
>>> On Mon, 27 Jul 2015, Michael Kerrisk (man-pages) wrote:
>>
>> ...
>>
>>>>        FUTEX_REQUEUE (since Linux 2.6.0)
>>>> .\" FIXME(Torvald) Is there some indication that FUTEX_REQUEUE is broken
>>>> .\"     in general, or is this comment implicitly speaking about the
>>>> .\"     condvar (?) use case? If the latter we might want to weaken the
>>>> .\"     advice below a little.
>>>> .\" [Anyone else have input on this?]
>>>
>>> The condvar use case exposes the flaw nicely, but that's pretty much
>>> true for everything which wants a sane requeue operation.
>>
>> In an earlier discussion I argued this point (that FUTURE_REQUEUE is broken and
>> should not be used in new code) and someone argued strongly against... stating
>> that there were legitimate uses for it. Of course I'm struggling to find the
>> thread and the reference at the moment - immensely useful, I know.
>>
>> I'll continue trying to find it and see if it can be useful here. I believe
>> Torvald was on the thread as well.
>>
> 
> Found it on libc-alpha, here it is for reference:
> 
> 	From: Rich Felker <dalias-8zAoT0mYgF4@public.gmane.org>
> 	Date: Wed, 29 Oct 2014 22:43:17 -0400
> 	To: Darren Hart <dvhart-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org>
> 	Cc: Carlos O'Donell <carlos-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>, Roland McGrath <roland-/Z5OmTQCD9xF6kxbq+BtvQ@public.gmane.org>,
> 	Torvald Riegel <triegel-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>, GLIBC Devel <libc-alpha-9JcytcrH/bA+uJoB2kUjGw@public.gmane.org>,
> 	Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> 	Subject: Re: Add futex wrapper to glibc?
> 
> 	On Wed, Oct 29, 2014 at 06:59:15PM -0700, Darren Hart wrote:
> 	> > We are IMO at the stage where futex is stable, few things are
> 	> > changing, and with documentation in place, I would consider adding a
> 	> > futex wrapper.
> 	> 
> 	> Yes, at least for the defined OP codes. New OPs may be added of
> 	> course, but that isn't a concern for supporting what exists today, and
> 	> doesn't break compatibility.
> 	> 
> 	> I wonder though... can we not wrap FUTEX_REQUEUE? It's fundamentally
> 	> broken.  FUTEX_CMP_REQUEUE should *always* be used instead. The glibc
> 	> wrapper is one way to encourage developers to do the right thing
> 	> (don't expose the bad op in the header).
> 
> 	You're mistaken here. There are plenty of valid ways to use
> 	FUTEX_REQUEUE - for example if the calling thread is requeuing the
> 	target(s) to a lock that the calling thread owns. Just because it
> 	doesn't meet the needs of the way glibc was using it internally
> 	doesn't mean it's useless for other applications.
> 
> 	In any case, I don't think there's a proposal to intercept/modify the
> 	commands to futex, just to pass them through (and possibly do a
> 	cancellable syscall for some of them).
> 
> 	Rich
> 
> 
>>>
>>>>               Avoid using this operation.  It is broken for its intended
>>>>               purpose.  Use FUTEX_CMP_REQUEUE instead.
>>>>
>>>>               This    operation    performs    the    same    task    as
>>>>               FUTEX_CMP_REQUEUE, except that no check is made using  the
>>>>               value in val3.  (The argument val3 is ignored.)

Thanks, Darren, that's really helpful! I've removed the statement in the man
page that FUTEX_REQUEUE is broken.

By the way, Darren. There were a couple of FIXMEs in the page where you are
explicitly mentioned by name. Could you take a look at those? Specifically,
the large block of text starting at:

    >> .\" FIXME XXX The following is my attempt at a definition of PI futexes,
    >> .\"       based on mail discussions with Darren Hart. Does it seem okay?

   (tglx looked at this and blessed it, but I'd like you also to check.)

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/