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: Torvald Riegel <triegel at redhat dot com>
- To: "Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>
- Cc: 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 16:34:53 +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>
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)!
> 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)?
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.
> 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...".
> 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.
Torvald