diff options
Diffstat (limited to 'man2/futex.2')
| -rw-r--r-- | man2/futex.2 | 66 |
1 files changed, 33 insertions, 33 deletions
diff --git a/man2/futex.2 b/man2/futex.2 index 43b1075..2ff300b 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -19,7 +19,7 @@ .\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail .\" http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242 .\" -.TH futex 2 2023-05-03 "Linux man-pages 6.05.01" +.TH futex 2 2023-10-31 "Linux man-pages 6.7" .SH NAME futex \- fast user-space locking .SH LIBRARY @@ -27,18 +27,18 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */" .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .B #include <unistd.h> -.PP +.P .BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \ ", uint32_t " val , .BI " const struct timespec *" timeout , \ " \fR /* or: \fBuint32_t \fIval2\fP */" .BI " uint32_t *" uaddr2 ", uint32_t " val3 ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR futex (), @@ -61,7 +61,7 @@ Other .BR futex () operations can be used to wake any processes or threads waiting for a particular condition. -.PP +.P A futex is a 32-bit value\[em]referred to below as a .IR "futex word" \[em]whose address is supplied to the @@ -80,7 +80,7 @@ virtual addresses in different processes, but these addresses all refer to the same location in physical memory.) In a multithreaded program, it is sufficient to place the futex word in a global variable shared by all threads. -.PP +.P 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 @@ -113,7 +113,7 @@ blocking via a futex is an atomic compare-and-block operation. .\" the reference in the following sentence .\" See NOTES for a detailed specification of .\" the synchronization semantics. -.PP +.P One use of futexes is for implementing locks. The state of the lock (i.e., acquired or not acquired) can be represented as an atomically accessed flag in shared memory. @@ -140,10 +140,10 @@ operation that wakes threads blocked on the lock flag used as a futex word See .BR futex (7) for more detail on how to use futexes. -.PP +.P Besides the basic wait and wake-up futex functionality, there are further futex operations aimed at supporting more complex use cases. -.PP +.P Note that no explicit initialization or destruction is necessary to use futexes; the kernel maintains a futex @@ -164,7 +164,7 @@ argument; .I val is a value whose meaning and purpose depends on .IR futex_op . -.PP +.P The remaining arguments .RI ( timeout , .IR uaddr2 , @@ -172,7 +172,7 @@ and .IR val3 ) are required only for certain of the futex operations described below. Where one of these arguments is not required, it is ignored. -.PP +.P For several blocking operations, the .I timeout argument is a pointer to a @@ -190,12 +190,12 @@ then to and in the remainder of this page, this argument is referred to as .I val2 when interpreted in this fashion. -.PP +.P Where it is required, the .I uaddr2 argument is a pointer to a second futex word that is employed by the operation. -.PP +.P The interpretation of the final integer argument, .IR val3 , depends on the operation. @@ -264,7 +264,7 @@ If this option is not set, the kernel measures the against the .B CLOCK_MONOTONIC clock. -.PP +.P The operation specified in .I futex_op is one of the following: @@ -835,7 +835,7 @@ while tasks at an intermediate priority continuously preempt the low-priority task from the CPU. Consequently, the low-priority task makes no progress toward releasing the lock, and the high-priority task remains blocked. -.PP +.P Priority inheritance is a mechanism for dealing with the priority-inversion problem. With this mechanism, when a high-priority task becomes blocked @@ -852,7 +852,7 @@ held by another intermediate-priority task then both of those tasks (or more generally, all of the tasks in a lock chain) have their priorities raised to be the same as the high-priority task. -.PP +.P From a user-space perspective, what makes a futex PI-aware is a policy agreement (described below) between user space and the kernel about the value of the futex word, @@ -868,7 +868,7 @@ for the implementation of very specific IPC mechanisms.) .\" talk about a PI aware pthread_mutex, than a PI aware futex, since .\" there is a lot of policy and scaffolding that has to be built up .\" around it to use it properly (this is what a PI pthread_mutex is). -.PP +.P .\" mtk: The following text is drawn from the Hart/Guniguntala paper .\" (listed in SEE ALSO), but I have reworded some pieces .\" significantly. @@ -899,7 +899,7 @@ FUTEX_WAITERS | TID (Note that is invalid for a PI futex word to have no owner and .B FUTEX_WAITERS set.) -.PP +.P With this policy in place, a user-space application can acquire an unacquired lock or release a lock using atomic instructions executed in user mode @@ -910,7 +910,7 @@ Acquiring a lock simply consists of using compare-and-swap to atomically set the futex word's value to the caller's TID if its previous value was 0. Releasing a lock requires using compare-and-swap to set the futex word's value to 0 if the previous value was the expected TID. -.PP +.P If a futex is already acquired (i.e., has a nonzero value), waiters must employ the .B FUTEX_LOCK_PI @@ -923,7 +923,7 @@ bit is set in the futex value; in this case, the lock owner must employ the .B FUTEX_UNLOCK_PI operation to release the lock. -.PP +.P In the cases where callers are forced into the kernel (i.e., required to perform a .BR futex () @@ -933,7 +933,7 @@ a kernel locking mechanism which implements the required priority-inheritance semantics. After the RT-mutex is acquired, the futex value is updated accordingly, before the calling thread returns to user space. -.PP +.P It is important to note .\" tglx (July 2015): .\" If there are multiple waiters on a pi futex then a wake pi operation @@ -950,7 +950,7 @@ up in an invalid state, such as having an owner but the value being 0, or having waiters but not having the .B FUTEX_WAITERS bit set.) -.PP +.P If a futex has an associated RT-mutex in the kernel (i.e., there are blocked waiters) and the owner of the futex/RT-mutex dies unexpectedly, @@ -969,7 +969,7 @@ the dead owner. .\" mechanism. In that case the futex value will be set to .\" FUTEX_OWNER_DIED. The robust futex mechanism is also available for non .\" PI futexes. -.PP +.P PI futexes are operated on by specifying one of the values listed below in .IR futex_op . Note that the PI futex operations must be used as paired operations @@ -1000,7 +1000,7 @@ Additionally, (or the error .B EINVAL results). -.PP +.P The PI futex operations are as follows: .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -1362,7 +1362,7 @@ was invoked via all operations return \-1 and set .I errno to indicate the error. -.PP +.P The return value on success depends on the operation, as described in the following list: .TP @@ -1742,7 +1742,7 @@ and the timeout expired before the operation completed. Linux. .SH HISTORY Linux 2.6.0. -.PP +.P Initial futex support was merged in Linux 2.5.7 but with different semantics from what was described above. A four-argument system call with the semantics @@ -1760,7 +1760,7 @@ The two processes each write messages to the terminal and employ a synchronization protocol that ensures that they alternate in writing messages. Upon running this program we see output such as the following: -.PP +.P .in +4n .EX $ \fB./futex_demo\fP @@ -1931,7 +1931,7 @@ main(int argc, char *argv[]) .BR pthread_mutexattr_getprotocol (3), .BR futex (7), .BR sched (7) -.PP +.P The following kernel source files: .IP \[bu] 3 .I Documentation/pi\-futex.txt @@ -1943,28 +1943,28 @@ The following kernel source files: .I Documentation/locking/rt\-mutex\-design.txt .IP \[bu] .I Documentation/robust\-futex\-ABI.txt -.PP +.P Franke, H., Russell, R., and Kirwood, M., 2002. \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP (from proceedings of the Ottawa Linux Symposium 2002), .br .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf .UE -.PP +.P Hart, D., 2009. \fIA futex overview and update\fP, .UR http://lwn.net/Articles/360699/ .UE -.PP +.P Hart, D.\& and Guniguntala, D., 2009. \fIRequeue-PI: Making glibc Condvars PI-Aware\fP (from proceedings of the 2009 Real-Time Linux Workshop), .UR http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf .UE -.PP +.P Drepper, U., 2011. \fIFutexes Are Tricky\fP, .UR http://www.akkadia.org/drepper/futex.pdf .UE -.PP +.P Futex example library, futex\-*.tar.bz2 at .br .UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ |