This is the mail archive of the
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: Darren Hart <dvhart at infradead dot org>
- Cc: mtk dot manpages at gmail dot com, Thomas Gleixner <tglx at linutronix dot de>, Torvald Riegel <triegel at redhat dot com>, 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: Wed, 16 Dec 2015 16:54:06 +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> <20151215211816 dot GR11972 at malice dot jf dot intel dot com>
On 12/15/2015 10:18 PM, Darren Hart wrote:
> On Tue, Dec 15, 2015 at 02:43:50PM +0100, Michael Kerrisk (man-pages) wrote:
>> 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
> Totally ordered with respect futex operations refers to semantics of the
> ACQUIRE/RELEASE operations and how they impact ordering of memory reads and
> writes. The kernel futex operations are protected by spinlocks, which ensure
> that that all operations are serialized with respect to one another.
> This is a lot to attempt to define in this document. Perhaps a reference to
> linux/Documentation/memory-barriers.txt as a footnote would be sufficient? Or
> perhaps for this manual, "serialized" would be sufficient, with a footnote
> regarding "totally ordered" and a pointer to the memory-barrier documentation?
I think I'll just settle for writing serialized in the man page, and be
done with it :-).
>> 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â
>> Futex operations
>> The futex_op argument consists of two parts: a command that specâ
>> ifies the operation to be performed, bit-wise ORed with zero or
>> or more options that modify the behaviour of the operation. The
>> options that may be included in futex_op are as follows:
>> FUTEX_CLOCK_REALTIME (since Linux 2.6.28)
>> This option bit can be employed only with the
>> FUTEX_WAIT_BITSET and FUTEX_WAIT_REQUEUE_PI operations.
> That caught me by surprise, but it's true. We reject FUTEX_WAIT |
> FUTEX_CLOCK_REALTIME, even though FUTEX_WAIT treated as FUTEX_WAIT_BITSET with
You uncover all sorts of interesting stuff when you document APIs ;-).
> Thomas, this looks like an oversight to me - do you recall if we intentionally
> disallow FUTEX_CLOCK_REALTIME with FUTEX_WAIT?
>> If this option is set, the kernel treats timeout as an
>> absolute time based on CLOCK_REALTIME.
>> If this option is not set, the kernel treats timeout as
>> relative time, measured against the CLOCK_MONOTONIC clock.
>> Priority-inheritance futexes
>> * 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 is invalid for a PI futex word to have no owner and
> ^ it
>> FUTEX_WAITERS set.)
>> FUTEX_TRYLOCK_PI (since Linux 2.6.18)
>> This operation tries to acquire the futex at uaddr. It is
>> 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
> The lock acquisition might succeed in the kernel because the futex word
Already did some rewording here which I think makes things better.
>> 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.
>> FIXME I think it would be helpful here to say a few more words about
>> the difference(s) between FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI.
>> Can someone propose something?
> Hrm. It seems pretty straightforward to me. I guess I'm too close to it. What
> about it seems unclear and needs clarification?
On reflection, I agree that the difference is perhaps well-enough explained.
Thanks for the comments, Darren.
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/