Darren Hart pointed me to the comments from Rich Felker
that there are valid use cases for FUTEX_REQUEUE.
From: Rich Felker <dalias@libc.org>
Date: Wed, 29 Oct 2014 22:43:17 -0400
To: Darren Hart <dvhart@infradead.org>
Cc: GLIBC Devel <libc-alpha@sourceware.org>, ...
Subject: Re: Add futex wrapper to glibc?
On Wed, Oct 29, 2014 at 06:59:15PM -0700, Darren Hart wrote:
[...]
> I wonder though... can we not wrap FUTEX_REQUEUE? It's fundamentally
> broken. FUTEX_CMP_REQUEUE should *always* be used instead. The glibc
> wrapper is one way to encourage developers to do the right thing
> (don't expose the bad op in the header).
You're mistaken here. There are plenty of valid ways to use
FUTEX_REQUEUE - for example if the calling thread is requeuing the
target(s) to a lock that the calling thread owns. Just because it
doesn't meet the needs of the way glibc was using it internally
doesn't mean it's useless for other applications.
Reported-by: Darren Hart <dvhart@infradead.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As commented on by Davidlohr Bueso:
This to me reads a bit too much into the kernel (fastpath,
refcnt, vmas). Why not just mention that it avoids overhead
in the kernel or something? I don't recall any manpage
mentioning such details, but I could be wrong.
Reported-by: Davidlohr Bueso <dave@stgolabs.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The kernel uses the following cast:
if (cmd == FUTEX_REQUEUE || cmd == FUTEX_CMP_REQUEUE ||
cmd == FUTEX_CMP_REQUEUE_PI || cmd == FUTEX_WAKE_OP)
val2 = (u32) (unsigned long) utime;
This ensures that always the least significant four bytes of the
pointer are used, both on ILP32 and LP64 systems.
On a big endian system a simple cast from 64 bit pointer to 32 bit
integer would return the most significant four bytes.
We have to make the reader of the man-page aware of the usage
of the least significant bytes.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Type u32 is not exposed to the user. Instead, refer to uint32_t,
which is defined in ISO/IEC 9899:1999.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Using the word "physical" address should make the text easier to
make.
Avoid negations like "may not be equal".
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Here is the result of a first pass over futex.2. I tried to
do nothing that is too controversial. I tried to apply the
terminology that at least Darren and I had in mind
consistently; but please check again.
The major changes are in how futexes are described in the
introductory parts of the page. I hope it's easier to understand
now. I've also tried to add some more precision to the the
description of the synchronization semantics (e.g., it makes a
difference whether we claim something is atomic (without further
qualification), or just atomic wrt. other futex operations).
In some cases, that adds some verbosity to the text -- but I
believe that this is worth the clarity and consistency in using
terms, for example.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The sentence is true for all man-pages. Remove it.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The abbreviation NPTL cannot be assumed to be common knowledge
of all readers of futex.7.
pthread.7 has details about the NPTL pthreads implementation.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
futex.7 is meant as overview of the usage of futexes. It should
point to the related man-pages.
pthreads are the main usage of futexes, refer to pthread.7.
Implementation of robust futexes requires knowledge of set_robust_list.2
and get_robust_list.2.
It is noworthy that a closing thread can wake up a futex. Hence mention
clone.2 and set_tid_address.2.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk