This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: futex(3) man page, final draft for pre-release review
- From: "Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>
- To: Torvald Riegel <triegel at redhat dot com>
- Cc: mtk dot manpages at gmail dot com, Thomas Gleixner <tglx at linutronix dot de>, Darren Hart <dvhart at infradead dot org>, lkml <linux-kernel at vger dot kernel dot org>, libc-alpha <libc-alpha at sourceware dot org>, linux-man <linux-man at vger dot kernel dot org>, Carlos O'Donell <carlos at redhat dot com>, Roland McGrath <roland at hack dot frob dot com>, Davidlohr Bueso <dave at stgolabs dot net>, Jakub Jelinek <jakub at redhat dot com>, Ingo Molnar <mingo at elte dot hu>, bill o gallmeister <bgallmeister at gmail dot com>, bert hubert <bert dot hubert at netherlabs dot nl>, Jan Kiszka <jan dot kiszka at siemens dot com>, Eric Dumazet <edumazet at google dot com>, Arnd Bergmann <arnd at arndb dot de>, Rusty Russell <rusty at rustcorp dot com dot au>, Heinrich Schuchardt <xypron dot glpk at gmx dot de>, Andy Lutomirski <luto at amacapital dot net>, Daniel Wagner <wagi at monom dot org>, Anton Blanchard <anton at samba dot org>, Steven Rostedt <rostedt at goodmis dot org>, Rich Felker <dalias at libc dot org>, Jonathan Wakely <jwakely at redhat dot com>, Mike Frysinger <vapier at gentoo dot org>
- Date: Tue, 15 Dec 2015 17:02:45 +0100
- Subject: Re: futex(3) man page, final draft for pre-release review
- Authentication-results: sourceware.org; auth=none
- References: <56701916 dot 4090203 at gmail dot com> <1450193693 dot 27311 dot 115 dot camel at localhost dot localdomain>
Hello Torvald,
On 12/15/2015 04:34 PM, Torvald Riegel wrote:
> On Tue, 2015-12-15 at 14:43 +0100, Michael Kerrisk (man-pages) wrote:
>> Hello all,
>>
>> After much too long a time, the revised futex man page *will*
>> go out in the next man pages release (it has been merged
>> into master).
>>
>> There are various places where the page could still be improved,
>> but it is much better (and more than 5 times longer) than the
>> existing page.
>
> This looks good to me; I just saw minor things (see below). Thank you
> for all the work you put into this (and to everybody who contributed)!
Hey Torvald, you were one of the biggest contributors, so, thanks!
>> When executing a futex operation that requests to block a thread,
>> the kernel will block only if the futex word has the value that
>> the calling thread supplied (as one of the arguments of the
>> futex() call) as the expected value of the futex word. The loadâ
>> ing of the futex word's value, the comparison of that value with
>> the expected value, and the actual blocking will happen atomiâ
>>
>> FIXME: for next line, it would be good to have an explanation of
>> "totally ordered" somewhere around here.
>>
>> cally and totally ordered with respect to concurrently executing
>> futex operations on the same futex word. Thus, the futex word is
>> used to connect the synchronization in user space with the impleâ
>> mentation of blocking by the kernel. Analogously to an atomic
>> compare-and-exchange operation that potentially changes shared
>> memory, blocking via a futex is an atomic compare-and-block operâ
>> ation.
>
> Maybe -- should we just say that it refers to the mathematical notion of
> a total order (or, technically, a strict total order in this case)?
I added a sentence along those lines.
> Though I would hope that everyone using futexes is roughly aware of the
> differences between partial and total orders.
>> FUTEX_TRYLOCK_PI (since Linux 2.6.18)
>> This operation tries to acquire the futex at uaddr. It is
>
> s/futex/lock/ to make it consistent with FUTEX_LOCK.
Done.
>> invoked when a user-space atomic acquire did not succeed
>> because the futex word was not 0.
>>
>>
>> FIXME(Next sentence) The wording "The trylock in kernel" below
>> needs clarification. Suggestions?
>>
>> The trylock in kernel might succeed because the futex word
>> contains stale state (FUTEX_WAITERS and/or
>> FUTEX_OWNER_DIED). This can happen when the owner of the
>> futex died. User space cannot handle this condition in a
>> race-free manner, but the kernel can fix this up and
>> acquire the futex.
>>
>> The uaddr2, val, timeout, and val3 arguments are ignored.
>
> What about "The acquisition of the lock might suceed if performed by the
> kernel in cases when the futex word contains stale state...".
Sounds good to me. Changed.
>> FUTEX_WAIT_REQUEUE_PI (since Linux 2.6.31)
>> Wait on a non-PI futex at uaddr and potentially be
>> requeued (via a FUTEX_CMP_REQUEUE_PI operation in another
>> task) onto a PI futex at uaddr2. The wait operation on
>> uaddr is the same as for FUTEX_WAIT.
>>
>> The waiter can be removed from the wait on uaddr without
>> requeueing on uaddr2 via a FUTEX_WAKE operation in another
>> task. In this case, the FUTEX_WAIT_REQUEUE_PI operation
>> returns with the error EWOULDBLOCK.
>
> This should be EAGAIN, I suppose, or the enumeration of errors should
> include EWOULDBLOCK.
Changed. BTW, under ERRORS there is already this text:
Note: on Linux, the symbolic names EAGAIN and EWOULDBLOCK
(both of which appear in different parts of the kernel
futex code) have the same value.
Thanks for the comments, Torvald!
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/