Futex manpages out of date

Futex manpages out of date

[Darren Hart]

The futex man-pages (2,7) from version 3.15-1 and at least a few earlier
versions are considerably out of date with respect to the current
implementation. They don't document newer op codes, such as:

FUTEX_WAIT_BITSET
FUTEX_WAKE_BITSET
FUTEX_WAKE_OP
FUTEX_LOCK_PI
FUTEX_UNLOCK_PI
FUTEX_WAIT_REQUEUE_PI
FUTEX_CMP_REQUEUE_PI

These new wait op codes now use absolute timeouts, while the original
FUTEX_WAIT uses a relative timeout. Lastly, and most importantly, glibc
has removed the futex() wrapper to syscall(SYS_futex, ...). With that in
mind, would people prefer that we simply remove the futex man-pages
(2,7)?

Thanks,

-- 
Darren Hart
IBM Linux Technology Center
Real-Time Linux Team
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Futex manpages out of date

[Peter Zijlstra]

On Fri, 2010-01-15 at 08:58 -0800, Darren Hart wrote:
> The futex man-pages (2,7) from version 3.15-1 and at least a few earlier
> versions are considerably out of date with respect to the current
> implementation. They don't document newer op codes, such as:
> 
> FUTEX_WAIT_BITSET
> FUTEX_WAKE_BITSET
> FUTEX_WAKE_OP
> FUTEX_LOCK_PI
> FUTEX_UNLOCK_PI
> FUTEX_WAIT_REQUEUE_PI
> FUTEX_CMP_REQUEUE_PI
> 
> These new wait op codes now use absolute timeouts, while the original
> FUTEX_WAIT uses a relative timeout. Lastly, and most importantly, glibc
> has removed the futex() wrapper to syscall(SYS_futex, ...). With that in
> mind, would people prefer that we simply remove the futex man-pages
> (2,7)?

A readable text about the interaction between the futex value and the
various futex ops and how to build proper locking primitives with them
would be helpful I think, however doing that in the form of a locking
library (as has been suggested at KS) seems plenty fine to me.

Readable code is much better than rambling English at conveying this
stuff.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Futex manpages out of date

[Darren Hart]

Peter Zijlstra wrote:
> On Fri, 2010-01-15 at 08:58 -0800, Darren Hart wrote:
>> The futex man-pages (2,7) from version 3.15-1 and at least a few earlier
>> versions are considerably out of date with respect to the current
>> implementation. They don't document newer op codes, such as:
>>
>> FUTEX_WAIT_BITSET
>> FUTEX_WAKE_BITSET
>> FUTEX_WAKE_OP
>> FUTEX_LOCK_PI
>> FUTEX_UNLOCK_PI
>> FUTEX_WAIT_REQUEUE_PI
>> FUTEX_CMP_REQUEUE_PI
>>
>> These new wait op codes now use absolute timeouts, while the original
>> FUTEX_WAIT uses a relative timeout. Lastly, and most importantly, glibc
>> has removed the futex() wrapper to syscall(SYS_futex, ...). With that in
>> mind, would people prefer that we simply remove the futex man-pages
>> (2,7)?
> 
> A readable text about the interaction between the futex value and the
> various futex ops and how to build proper locking primitives with them
> would be helpful I think, however doing that in the form of a locking
> library (as has been suggested at KS) seems plenty fine to me.
> 
> Readable code is much better than rambling English at conveying this
> stuff.

Perhaps as part of futex-test? An example set of locking primitives 
would be a good way to test the syscall independently of glibc...


-- 
Darren Hart
IBM Linux Technology Center
Real-Time Linux Team
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Futex manpages out of date

[Peter Zijlstra]

On Fri, 2010-01-15 at 09:13 -0800, Darren Hart wrote:
> Peter Zijlstra wrote:
> > On Fri, 2010-01-15 at 08:58 -0800, Darren Hart wrote:
> >> The futex man-pages (2,7) from version 3.15-1 and at least a few earlier
> >> versions are considerably out of date with respect to the current
> >> implementation. They don't document newer op codes, such as:
> >>
> >> FUTEX_WAIT_BITSET
> >> FUTEX_WAKE_BITSET
> >> FUTEX_WAKE_OP
> >> FUTEX_LOCK_PI
> >> FUTEX_UNLOCK_PI
> >> FUTEX_WAIT_REQUEUE_PI
> >> FUTEX_CMP_REQUEUE_PI
> >>
> >> These new wait op codes now use absolute timeouts, while the original
> >> FUTEX_WAIT uses a relative timeout. Lastly, and most importantly, glibc
> >> has removed the futex() wrapper to syscall(SYS_futex, ...). With that in
> >> mind, would people prefer that we simply remove the futex man-pages
> >> (2,7)?
> > 
> > A readable text about the interaction between the futex value and the
> > various futex ops and how to build proper locking primitives with them
> > would be helpful I think, however doing that in the form of a locking
> > library (as has been suggested at KS) seems plenty fine to me.
> > 
> > Readable code is much better than rambling English at conveying this
> > stuff.
> 
> Perhaps as part of futex-test? An example set of locking primitives 
> would be a good way to test the syscall independently of glibc...

Sure, and if that ever grows into what benh wants then we're good I
think ;-)

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Futex manpages out of date

[Petr Baudis]

On Fri, Jan 15, 2010 at 06:11:24PM +0100, Peter Zijlstra wrote:
> On Fri, 2010-01-15 at 08:58 -0800, Darren Hart wrote:
> > The futex man-pages (2,7) from version 3.15-1 and at least a few earlier
> > versions are considerably out of date with respect to the current
> > implementation. They don't document newer op codes, such as:
> > 
> > FUTEX_WAIT_BITSET
> > FUTEX_WAKE_BITSET
> > FUTEX_WAKE_OP
> > FUTEX_LOCK_PI
> > FUTEX_UNLOCK_PI
> > FUTEX_WAIT_REQUEUE_PI
> > FUTEX_CMP_REQUEUE_PI
> > 
> > These new wait op codes now use absolute timeouts, while the original
> > FUTEX_WAIT uses a relative timeout. Lastly, and most importantly, glibc
> > has removed the futex() wrapper to syscall(SYS_futex, ...). With that in
> > mind, would people prefer that we simply remove the futex man-pages
> > (2,7)?
> 
> A readable text about the interaction between the futex value and the
> various futex ops and how to build proper locking primitives with them
> would be helpful I think, however doing that in the form of a locking
> library (as has been suggested at KS) seems plenty fine to me.
> 
> Readable code is much better than rambling English at conveying this
> stuff.

http://people.redhat.com/drepper/futex.pdf is pretty good description,
unfortunately also outdated by now. Perhaps it would be interesting to
convert this into some kind of wiki form with Ulrich's permission?

				Petr "Pasky" Baudis
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Futex manpages out of date

[Darren Hart]

Petr Baudis wrote:
> On Fri, Jan 15, 2010 at 06:11:24PM +0100, Peter Zijlstra wrote:
>> On Fri, 2010-01-15 at 08:58 -0800, Darren Hart wrote:
>>> The futex man-pages (2,7) from version 3.15-1 and at least a few earlier
>>> versions are considerably out of date with respect to the current
>>> implementation. They don't document newer op codes, such as:
>>>
>>> FUTEX_WAIT_BITSET
>>> FUTEX_WAKE_BITSET
>>> FUTEX_WAKE_OP
>>> FUTEX_LOCK_PI
>>> FUTEX_UNLOCK_PI
>>> FUTEX_WAIT_REQUEUE_PI
>>> FUTEX_CMP_REQUEUE_PI
>>>
>>> These new wait op codes now use absolute timeouts, while the original
>>> FUTEX_WAIT uses a relative timeout. Lastly, and most importantly, glibc
>>> has removed the futex() wrapper to syscall(SYS_futex, ...). With that in
>>> mind, would people prefer that we simply remove the futex man-pages
>>> (2,7)?
>> A readable text about the interaction between the futex value and the
>> various futex ops and how to build proper locking primitives with them
>> would be helpful I think, however doing that in the form of a locking
>> library (as has been suggested at KS) seems plenty fine to me.
>>
>> Readable code is much better than rambling English at conveying this
>> stuff.
> 
> http://people.redhat.com/drepper/futex.pdf is pretty good description,
> unfortunately also outdated by now. Perhaps it would be interesting to
> convert this into some kind of wiki form with Ulrich's permission?

Does anyone know what is being done documentation-wise with other 
syscalls? I believe glibc has removed other wrappers as well. In my 
opinion the best place for this is in the linux kernel Documentation 
directory. I have already documented requeue_pi there. Ulrich's paper 
would server as an excellent starting point for a sysfutex.txt or 
futex_usage.txt file.

Ulrich, do you have a preference or any requirements on how your work is 
used?

-- 
Darren Hart
IBM Linux Technology Center
Real-Time Linux Team
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Futex manpages out of date

[Peter Zijlstra]

On Mon, 2010-01-18 at 17:40 +0100, Petr Baudis wrote:
> On Fri, Jan 15, 2010 at 06:11:24PM +0100, Peter Zijlstra wrote:
> > On Fri, 2010-01-15 at 08:58 -0800, Darren Hart wrote:
> > > The futex man-pages (2,7) from version 3.15-1 and at least a few earlier
> > > versions are considerably out of date with respect to the current
> > > implementation. They don't document newer op codes, such as:
> > > 
> > > FUTEX_WAIT_BITSET
> > > FUTEX_WAKE_BITSET
> > > FUTEX_WAKE_OP
> > > FUTEX_LOCK_PI
> > > FUTEX_UNLOCK_PI
> > > FUTEX_WAIT_REQUEUE_PI
> > > FUTEX_CMP_REQUEUE_PI
> > > 
> > > These new wait op codes now use absolute timeouts, while the original
> > > FUTEX_WAIT uses a relative timeout. Lastly, and most importantly, glibc
> > > has removed the futex() wrapper to syscall(SYS_futex, ...). With that in
> > > mind, would people prefer that we simply remove the futex man-pages
> > > (2,7)?
> > 
> > A readable text about the interaction between the futex value and the
> > various futex ops and how to build proper locking primitives with them
> > would be helpful I think, however doing that in the form of a locking
> > library (as has been suggested at KS) seems plenty fine to me.
> > 
> > Readable code is much better than rambling English at conveying this
> > stuff.
> 
> http://people.redhat.com/drepper/futex.pdf is pretty good description,
> unfortunately also outdated by now. Perhaps it would be interesting to
> convert this into some kind of wiki form with Ulrich's permission?

People keep saying that, but I found it highly unreadable.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Futex manpages out of date

[Darren Hart]

Peter Zijlstra wrote:
> On Mon, 2010-01-18 at 17:40 +0100, Petr Baudis wrote:
>> On Fri, Jan 15, 2010 at 06:11:24PM +0100, Peter Zijlstra wrote:
>>> On Fri, 2010-01-15 at 08:58 -0800, Darren Hart wrote:
>>>> The futex man-pages (2,7) from version 3.15-1 and at least a few earlier
>>>> versions are considerably out of date with respect to the current
>>>> implementation. They don't document newer op codes, such as:
>>>>
>>>> FUTEX_WAIT_BITSET
>>>> FUTEX_WAKE_BITSET
>>>> FUTEX_WAKE_OP
>>>> FUTEX_LOCK_PI
>>>> FUTEX_UNLOCK_PI
>>>> FUTEX_WAIT_REQUEUE_PI
>>>> FUTEX_CMP_REQUEUE_PI
>>>>
>>>> These new wait op codes now use absolute timeouts, while the original
>>>> FUTEX_WAIT uses a relative timeout. Lastly, and most importantly, glibc
>>>> has removed the futex() wrapper to syscall(SYS_futex, ...). With that in
>>>> mind, would people prefer that we simply remove the futex man-pages
>>>> (2,7)?
>>> A readable text about the interaction between the futex value and the
>>> various futex ops and how to build proper locking primitives with them
>>> would be helpful I think, however doing that in the form of a locking
>>> library (as has been suggested at KS) seems plenty fine to me.
>>>
>>> Readable code is much better than rambling English at conveying this
>>> stuff.
>> http://people.redhat.com/drepper/futex.pdf is pretty good description,
>> unfortunately also outdated by now. Perhaps it would be interesting to
>> convert this into some kind of wiki form with Ulrich's permission?
> 
> People keep saying that, but I found it highly unreadable.

Interesting. I found it to be a good introduction into the usage of 
futexes as well as cautionary of the many non-obvious race conditions 
possible with locking structures built on futexes.


-- 
Darren Hart
IBM Linux Technology Center
Real-Time Linux Team
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html