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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

On 08/19/2015 03:40 PM, Thomas Gleixner wrote:
> On Wed, 5 Aug 2015, Darren Hart wrote:
>> On Mon, Jul 27, 2015 at 02:07:15PM +0200, Michael Kerrisk (man-pages) wrote:
>>> .\" FIXME XXX ===== Start of adapted Hart/Guniguntala text =====
>>> .\"       The following text is drawn from the Hart/Guniguntala paper
>>> .\"       (listed in SEE ALSO), but I have reworded some pieces
>>> .\"       significantly. Please check it.
>>>
>>>        The PI futex operations described below  differ  from  the  other
>>>        futex  operations  in  that  they impose policy on the use of the
>>>        value of the futex word:
>>>
>>>        *  If the lock is not acquired, the futex word's value  shall  be
>>>           0.
>>>
>>>        *  If  the  lock is acquired, the futex word's value shall be the
>>>           thread ID (TID; see gettid(2)) of the owning thread.
>>>
>>>        *  If the lock is owned and there are threads contending for  the
>>>           lock,  then  the  FUTEX_WAITERS  bit shall be set in the futex
>>>           word's value; in other words, this value is:
>>>
>>>               FUTEX_WAITERS | TID
>>>
>>>
>>>        Note that a PI futex word never just has the value FUTEX_WAITERS,
>>>        which is a permissible state for non-PI futexes.
>>
>> The second clause is inappropriate. I don't know if that was yours or
>> mine, but non-PI futexes do not have a kernel defined value policy, so
>> ==FUTEX_WAITERS cannot be a "permissible state" as any value is
>> permissible for non-PI futexes, and none have a kernel defined state.
> 
> Depends. If the regular futex is configured as robust, then we have a
> kernel defined value policy as well.

Okay -- so do we need a change to the text here?

>>> .\" FIXME I'm not quite clear on the meaning of the following sentence.
>>> .\"       Is this trying to say that while blocked in a
>>> .\"       FUTEX_WAIT_REQUEUE_PI, it could happen that another
>>> .\"       task does a FUTEX_WAKE on uaddr that simply causes
>>> .\"       a normal wake, with the result that the FUTEX_WAIT_REQUEUE_PI
>>> .\"       does not complete? What happens then to the FUTEX_WAIT_REQUEUE_PI
>>> .\"       opertion? Does it remain blocked, or does it unblock
>>> .\"       In which case, what does user space see?
>>>
>>>               The
>>>               waiter   can  be  removed  from  the  wait  on  uaddr  via
>>>               FUTEX_WAKE without requeueing on uaddr2.
>>
>> Userspace should see the task wake and continue executing. This would
>> effectively be a cancelation operation - which I didn't think was
>> supported. Thomas?
> 
> We probably never intended to support it, but looking at the code it
> works (did not try it though). It returns to user space with
> -EWOULDBLOCK. So it basically behaves like any other spurious wakeup.

Again, I assume no changes are required to the man page(?).

Cheers,

Michael

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