mirror of https://github.com/mkerrisk/man-pages
futex.2: Process/thread rewordings
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
a59564304a
commit
bdc5957afa
64
man2/futex.2
64
man2/futex.2
|
@ -50,8 +50,8 @@ described in
|
||||||
When a futex operation did not finish uncontended in user space, a
|
When a futex operation did not finish uncontended in user space, a
|
||||||
.BR futex ()
|
.BR futex ()
|
||||||
call needs to be made to the kernel to arbitrate.
|
call needs to be made to the kernel to arbitrate.
|
||||||
Arbitration can either mean putting the calling
|
Arbitration can either mean putting the caller
|
||||||
process to sleep or, conversely, waking a waiting process.
|
to sleep or, conversely, waking a waiting process or thread.
|
||||||
.PP
|
.PP
|
||||||
Callers of
|
Callers of
|
||||||
.BR futex ()
|
.BR futex ()
|
||||||
|
@ -185,7 +185,7 @@ then the call fails immediately with the error
|
||||||
.BR EAGAIN .
|
.BR EAGAIN .
|
||||||
.\" FIXME I added the following sentence. Please confirm that it is correct.
|
.\" FIXME I added the following sentence. Please confirm that it is correct.
|
||||||
The purpose of the test step is to detect races where
|
The purpose of the test step is to detect races where
|
||||||
another process changes the value of the futex between
|
another process or thread changes the value of the futex between
|
||||||
the time it was last checked and the time of the
|
the time it was last checked and the time of the
|
||||||
.BR FUTEX_WAIT
|
.BR FUTEX_WAIT
|
||||||
operation.
|
operation.
|
||||||
|
@ -213,7 +213,8 @@ are ignored.
|
||||||
For
|
For
|
||||||
.BR futex (7),
|
.BR futex (7),
|
||||||
this call is executed if decrementing the count gave a negative value
|
this call is executed if decrementing the count gave a negative value
|
||||||
(indicating contention), and will sleep until another process releases
|
(indicating contention),
|
||||||
|
and will sleep until another process or thread releases
|
||||||
the futex and executes the
|
the futex and executes the
|
||||||
.B FUTEX_WAKE
|
.B FUTEX_WAKE
|
||||||
operation.
|
operation.
|
||||||
|
@ -225,7 +226,7 @@ operation.
|
||||||
.\" Strictly speaking, since Linux 2.5.x
|
.\" Strictly speaking, since Linux 2.5.x
|
||||||
This operation wakes at most
|
This operation wakes at most
|
||||||
.I val
|
.I val
|
||||||
processes waiting (i.e., inside
|
of the waiters that are waiting (i.e., inside
|
||||||
.BR FUTEX_WAIT )
|
.BR FUTEX_WAIT )
|
||||||
on the futex at the address
|
on the futex at the address
|
||||||
.IR uaddr .
|
.IR uaddr .
|
||||||
|
@ -259,8 +260,8 @@ once the futex value has been set to 1 (indicating that it is available).
|
||||||
.\" Strictly speaking, from Linux 2.5.x to 2.6.25
|
.\" Strictly speaking, from Linux 2.5.x to 2.6.25
|
||||||
This operation creates a file descriptor that is associated with the futex at
|
This operation creates a file descriptor that is associated with the futex at
|
||||||
.IR uaddr .
|
.IR uaddr .
|
||||||
The calling process must close the returned file descriptor after use.
|
The caller must close the returned file descriptor after use.
|
||||||
When another process performs a
|
When another process or thread performs a
|
||||||
.BR FUTEX_WAKE
|
.BR FUTEX_WAKE
|
||||||
on the futex, the file descriptor indicates as being readable with
|
on the futex, the file descriptor indicates as being readable with
|
||||||
.BR select (2),
|
.BR select (2),
|
||||||
|
@ -271,7 +272,7 @@ and
|
||||||
The file descriptor can be used to obtain asynchronous notifications:
|
The file descriptor can be used to obtain asynchronous notifications:
|
||||||
if
|
if
|
||||||
.I val
|
.I val
|
||||||
is nonzero, then when another process executes a
|
is nonzero, then when another process or thread executes a
|
||||||
.BR FUTEX_WAKE ,
|
.BR FUTEX_WAKE ,
|
||||||
the caller will receive the signal number that was passed in
|
the caller will receive the signal number that was passed in
|
||||||
.IR val .
|
.IR val .
|
||||||
|
@ -329,7 +330,8 @@ the
|
||||||
.BR FUTEX_CMP_REQUEUE
|
.BR FUTEX_CMP_REQUEUE
|
||||||
operation is used to avoid a "thundering herd" effect when
|
operation is used to avoid a "thundering herd" effect when
|
||||||
.B FUTEX_WAKE
|
.B FUTEX_WAKE
|
||||||
is used and all processes woken up need to acquire another futex.
|
is used and all of the waiters that are woken up
|
||||||
|
need to acquire another futex.
|
||||||
It differs from
|
It differs from
|
||||||
.BR FUTEX_REQUEUE
|
.BR FUTEX_REQUEUE
|
||||||
in that it first checks whether the location
|
in that it first checks whether the location
|
||||||
|
@ -632,27 +634,27 @@ Linux supports priority-inheritance (PI) futexes in order to handle
|
||||||
priority-inversion problems that can be encountered with
|
priority-inversion problems that can be encountered with
|
||||||
normal futex locks.
|
normal futex locks.
|
||||||
Priority inversion is the problem that occurs when a high-priority
|
Priority inversion is the problem that occurs when a high-priority
|
||||||
process is blocked waiting to acquire a lock held by a low-priority process,
|
task is blocked waiting to acquire a lock held by a low-priority task,
|
||||||
while processes at an intermediate priority continuously preempt
|
while tasks at an intermediate priority continuously preempt
|
||||||
the low-priority process from the CPU.
|
the low-priority task from the CPU.
|
||||||
Consequently, the low-priority process makes no progress toward
|
Consequently, the low-priority task makes no progress toward
|
||||||
releasing the lock, and the high-priority process remains blocked.
|
releasing the lock, and the high-priority task remains blocked.
|
||||||
|
|
||||||
Priority inheritance is a mechanism for dealing with
|
Priority inheritance is a mechanism for dealing with
|
||||||
the priority-inversion problem.
|
the priority-inversion problem.
|
||||||
With this mechanism, when a high-priority process becomes blocked
|
With this mechanism, when a high-priority task becomes blocked
|
||||||
by a lock held by a low-priority process,
|
by a lock held by a low-priority task,
|
||||||
the latter's priority is temporarily raised to that of the former,
|
the latter's priority is temporarily raised to that of the former,
|
||||||
so that it is not preempted by any intermediate level processes,
|
so that it is not preempted by any intermediate level tasks,
|
||||||
and can thus make progress toward releasing the lock.
|
and can thus make progress toward releasing the lock.
|
||||||
To be effective, priority inheritance must be transitive,
|
To be effective, priority inheritance must be transitive,
|
||||||
meaning that if a high-priority process blocks on a lock
|
meaning that if a high-priority task blocks on a lock
|
||||||
held by a lower-priority process that is itself blocked by lock
|
held by a lower-priority task that is itself blocked by lock
|
||||||
held by another intermediate-priority process
|
held by another intermediate-priority task
|
||||||
(and so on, for chains of arbitrary length),
|
(and so on, for chains of arbitrary length),
|
||||||
then both of those process
|
then both of those task
|
||||||
(or more generally, all of the processes in a lock chain)
|
(or more generally, all of the tasks in a lock chain)
|
||||||
have their priorities raised to be the same as the high-priority process.
|
have their priorities raised to be the same as the high-priority task.
|
||||||
|
|
||||||
.\" FIXME ===== Start of adapted Hart/Guniguntala text =====
|
.\" FIXME ===== Start of adapted Hart/Guniguntala text =====
|
||||||
.\" The following text is drawn from the Hart/Guniguntala paper,
|
.\" The following text is drawn from the Hart/Guniguntala paper,
|
||||||
|
@ -972,23 +974,24 @@ The return value on success depends on the operation,
|
||||||
as described in the following list:
|
as described in the following list:
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_WAIT
|
.B FUTEX_WAIT
|
||||||
Returns 0 if the process was woken by a
|
Returns 0 if the caller was woken by a
|
||||||
.B FUTEX_WAKE
|
.B FUTEX_WAKE
|
||||||
or
|
or
|
||||||
.B FUTEX_WAKE_BITSET
|
.B FUTEX_WAKE_BITSET
|
||||||
call.
|
call.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_WAKE
|
.B FUTEX_WAKE
|
||||||
Returns the number of processes woken up.
|
Returns the number of waiters that were woken up.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_FD
|
.B FUTEX_FD
|
||||||
Returns the new file descriptor associated with the futex.
|
Returns the new file descriptor associated with the futex.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_REQUEUE
|
.B FUTEX_REQUEUE
|
||||||
Returns the number of processes woken up.
|
Returns the number of waiters that were woken up.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_CMP_REQUEUE
|
.B FUTEX_CMP_REQUEUE
|
||||||
Returns the total number of processes woken up or requeued to the futex at
|
Returns the total number of waiters that were woken up or
|
||||||
|
requeued to the futex at
|
||||||
.IR uaddr2 .
|
.IR uaddr2 .
|
||||||
If this value is greater than
|
If this value is greater than
|
||||||
.IR val ,
|
.IR val ,
|
||||||
|
@ -1005,7 +1008,7 @@ and
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_WAIT_BITSET
|
.B FUTEX_WAIT_BITSET
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME Is the following correct?
|
||||||
Returns 0 if the process was woken by a
|
Returns 0 if the caller was woken by a
|
||||||
.B FUTEX_WAKE
|
.B FUTEX_WAKE
|
||||||
or
|
or
|
||||||
.B FUTEX_WAKE_BITSET
|
.B FUTEX_WAKE_BITSET
|
||||||
|
@ -1013,7 +1016,7 @@ call.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_WAKE_BITSET
|
.B FUTEX_WAKE_BITSET
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME Is the following correct?
|
||||||
Returns the number of processes woken up.
|
Returns the number of waiters that were woken up.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_LOCK_PI
|
.B FUTEX_LOCK_PI
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME Is the following correct?
|
||||||
|
@ -1029,7 +1032,8 @@ Returns 0 if the futex was successfully unlocked.
|
||||||
.TP
|
.TP
|
||||||
.B FUTEX_CMP_REQUEUE_PI
|
.B FUTEX_CMP_REQUEUE_PI
|
||||||
.\" FIXME Is the following correct?
|
.\" FIXME Is the following correct?
|
||||||
Returns the total number of processes woken up or requeued to the futex at
|
Returns the total number of waiters that were woken up or
|
||||||
|
requeued to the futex at
|
||||||
.IR uaddr2 .
|
.IR uaddr2 .
|
||||||
If this value is greater than
|
If this value is greater than
|
||||||
.IR val ,
|
.IR val ,
|
||||||
|
|
Loading…
Reference in New Issue