From: Alejandro Colomar Date: Thu, 29 May 2025 11:33:23 +0000 (+0200) Subject: man/man2/futex.2, man/man2const/FUTEX_WAIT_BITSET.2const: Split FUTEX_WAIT_BITSET... X-Git-Tag: man-pages-6.15~43^2~14 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ae663a6ba8e5e4cb3f2e3cd0c7c6a98f3a27065b;p=thirdparty%2Fman-pages.git man/man2/futex.2, man/man2const/FUTEX_WAIT_BITSET.2const: Split FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET from futex(2) Signed-off-by: Alejandro Colomar --- diff --git a/man/man2/futex.2 b/man/man2/futex.2 index 9b2b1f528..781a270b1 100644 --- a/man/man2/futex.2 +++ b/man/man2/futex.2 @@ -227,7 +227,7 @@ and so on. .BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)" .\" commit 1acdac104668a0834cfa267de9946fac7764d486 This option bit can be employed only with the -.BR FUTEX_WAIT_BITSET , +.BR FUTEX_WAIT_BITSET (2const), .BR FUTEX_WAIT_REQUEUE_PI , (since Linux 4.5) .\" commit 337f13046ff03717a9e99675284a817527440a49 @@ -268,116 +268,10 @@ is one of the following: .BR FUTEX_CMP_REQUEUE (2const) .TQ .BR FUTEX_WAKE_OP (2const) -.TP -.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)" -.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d -This operation is like -.BR FUTEX_WAIT (2const) -except that -.I val3 -is used to provide a 32-bit bit mask to the kernel. -This bit mask, in which at least one bit must be set, -is stored in the kernel-internal state of the waiter. -See the description of -.B FUTEX_WAKE_BITSET -for further details. -.IP -If -.I timeout -is not NULL, the structure it points to specifies -an absolute timeout for the wait operation. -If -.I timeout -is NULL, the operation can block indefinitely. -.IP -The -.I uaddr2 -argument is ignored. -.\" -.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.\" -.TP -.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)" -.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d -This operation is the same as -.BR FUTEX_WAKE (2const) -except that the -.I val3 -argument is used to provide a 32-bit bit mask to the kernel. -This bit mask, in which at least one bit must be set, -is used to select which waiters should be woken up. -The selection is done by a bitwise AND of the "wake" bit mask -(i.e., the value in -.IR val3 ) -and the bit mask which is stored in the kernel-internal -state of the waiter (the "wait" bit mask that is set using -.BR FUTEX_WAIT_BITSET ). -All of the waiters for which the result of the AND is nonzero are woken up; -the remaining waiters are left sleeping. -.IP -The effect of -.B FUTEX_WAIT_BITSET -and -.B FUTEX_WAKE_BITSET -is to allow selective wake-ups among multiple waiters that are blocked -on the same futex. -However, note that, depending on the use case, -employing this bit-mask multiplexing feature on a -futex can be less efficient than simply using multiple futexes, -because employing bit-mask multiplexing requires the kernel -to check all waiters on a futex, -including those that are not interested in being woken up -(i.e., they do not have the relevant bit set in their "wait" bit mask). -.\" According to http://locklessinc.com/articles/futex_cheat_sheet/: -.\" -.\" "The original reason for the addition of these extensions -.\" was to improve the performance of pthread read-write locks -.\" in glibc. However, the pthreads library no longer uses the -.\" same locking algorithm, and these extensions are not used -.\" without the bitset parameter being all ones. -.\" -.\" The page goes on to note that the FUTEX_WAIT_BITSET operation -.\" is nevertheless used (with a bit mask of all ones) in order to -.\" obtain the absolute timeout functionality that is useful -.\" for efficiently implementing Pthreads APIs (which use absolute -.\" timeouts); FUTEX_WAIT provides only relative timeouts. -.IP -The constant -.BR FUTEX_BITSET_MATCH_ANY , -which corresponds to all 32 bits set in the bit mask, can be used as the -.I val3 -argument for -.B FUTEX_WAIT_BITSET -and -.BR FUTEX_WAKE_BITSET . -Other than differences in the handling of the -.I timeout -argument, the -.BR FUTEX_WAIT (2const) -operation is equivalent to -.B FUTEX_WAIT_BITSET -with -.I val3 -specified as -.BR FUTEX_BITSET_MATCH_ANY ; -that is, allow a wake-up by any waker. -The -.BR FUTEX_WAKE (2const) -operation is equivalent to -.B FUTEX_WAKE_BITSET -with -.I val3 -specified as -.BR FUTEX_BITSET_MATCH_ANY ; -that is, wake up any waiter(s). -.IP -The -.I uaddr2 -and -.I timeout -arguments are ignored. -.\" -.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.TQ +.BR FUTEX_WAIT_BITSET (2const) +.TQ +.BR FUTEX_WAKE_BITSET (2const) .\" .SS Priority-inheritance futexes Linux supports priority-inheritance (PI) futexes in order to handle @@ -918,15 +812,6 @@ is set to indicate the error. The return value on success depends on the operation, as described in the following list: .TP -.B FUTEX_WAIT_BITSET -Returns 0 if the caller was woken up. -See -.BR FUTEX_WAIT (2const) -for how to interpret this correctly in practice. -.TP -.B FUTEX_WAKE_BITSET -Returns the number of waiters that were woken up. -.TP .B FUTEX_LOCK_PI Returns 0 if the futex was successfully locked. .TP @@ -962,8 +847,7 @@ the futex word at No read access to the memory of a futex word. .TP .B EAGAIN -.RB ( FUTEX_WAIT_BITSET , -.BR FUTEX_WAIT_REQUEUE_PI ) +.RB ( FUTEX_WAIT_REQUEUE_PI ) The value pointed to by .I uaddr was not equal to the expected value @@ -1032,14 +916,6 @@ or .IR timeout ) did not point to a valid user-space address. .TP -.B EINTR -A -.B FUTEX_WAIT_BITSET -operation was interrupted by a signal (see -.BR signal (7)). -Before Linux 2.6.22, this error could also be returned for -a spurious wakeup; since Linux 2.6.22, this no longer happens. -.TP .B EINVAL The operation in .I futex_op @@ -1065,13 +941,6 @@ but it does not point to a valid object\[em]that is, the address is not four-byte-aligned. .TP .B EINVAL -.RB ( FUTEX_WAIT_BITSET , -.BR FUTEX_WAKE_BITSET ) -The bit mask supplied in -.I val3 -is zero. -.TP -.B EINVAL .RB ( FUTEX_CMP_REQUEUE_PI ) .I uaddr equals @@ -1079,17 +948,6 @@ equals (i.e., an attempt was made to requeue to the same futex). .TP .B EINVAL -.RB ( FUTEX_WAKE_BITSET ) -The kernel detected an inconsistency between the user-space state at -.I uaddr -and the kernel state\[em]that is, it detected a waiter which waits in -.B FUTEX_LOCK_PI -or -.B FUTEX_LOCK_PI2 -on -.IR uaddr . -.TP -.B EINVAL .RB ( FUTEX_LOCK_PI , .BR FUTEX_LOCK_PI2 , .BR FUTEX_TRYLOCK_PI , @@ -1103,7 +961,7 @@ or that the kernel found a waiter on which is waiting via .BR FUTEX_WAIT (2const) or -.BR FUTEX_WAIT_BITSET . +.BR FUTEX_WAIT_BITSET (2const). .TP .B EINVAL .RB ( FUTEX_CMP_REQUEUE_PI ) @@ -1116,7 +974,7 @@ and the kernel state; that is, the kernel detected a waiter which waits via .BR FUTEX_WAIT (2const) or -.B FUTEX_WAIT_BITSET +.BR FUTEX_WAIT_BITSET (2const) on .IR uaddr2 . .TP @@ -1128,7 +986,7 @@ and the kernel state; that is, the kernel detected a waiter which waits via .BR FUTEX_WAIT (2const) or -.B FUTEX_WAIT_BITSET +.BR FUTEX_WAIT_BITSET (2const) on .IR uaddr . .TP @@ -1182,7 +1040,7 @@ The option was specified in .IR futex_op , but the accompanying operation was neither -.BR FUTEX_WAIT_BITSET , +.BR FUTEX_WAIT_BITSET (2const), .BR FUTEX_WAIT_REQUEUE_PI , nor .BR FUTEX_LOCK_PI2 . diff --git a/man/man2const/FUTEX_WAIT_BITSET.2const b/man/man2const/FUTEX_WAIT_BITSET.2const new file mode 100644 index 000000000..bb220cbcb --- /dev/null +++ b/man/man2const/FUTEX_WAIT_BITSET.2const @@ -0,0 +1,218 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" may be freely modified and distributed +.\" %%%LICENSE_END +.\" +.TH FUTEX_WAIT_BITSET 2const (date) "Linux man-pages (unreleased)" +.SH NAME +FUTEX_WAIT_BITSET, +FUTEX_WAKE_BITSET +\- +selective futex waiting and waking +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " FUTEX_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAIT_BITSET, uint32_t " val , +.BI " const struct timespec *" timeout ", NULL," +.BI " uint32_t " val3 ); +.P +.BI "long syscall(SYS_futex, uint32_t *" uaddr ", FUTEX_WAKE_BITSET, uint32_t " val , +.B " NULL, NULL," +.BI " uint32_t " val3 ); +.fi +.SH DESCRIPTION +.TP +.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)" +.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d +This operation is like +.BR FUTEX_WAIT (2const) +except that +.I val3 +is used to provide a 32-bit bit mask to the kernel. +This bit mask, in which at least one bit must be set, +is stored in the kernel-internal state of the waiter. +See the description of +.B FUTEX_WAKE_BITSET +for further details. +.IP +If +.I timeout +is not NULL, the structure it points to specifies +an absolute timeout for the wait operation. +If +.I timeout +is NULL, the operation can block indefinitely. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)" +.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d +This operation is the same as +.BR FUTEX_WAKE (2const) +except that the +.I val3 +argument is used to provide a 32-bit bit mask to the kernel. +This bit mask, in which at least one bit must be set, +is used to select which waiters should be woken up. +The selection is done by a bitwise AND of the "wake" bit mask +(i.e., the value in +.IR val3 ) +and the bit mask which is stored in the kernel-internal +state of the waiter (the "wait" bit mask that is set using +.BR FUTEX_WAIT_BITSET ). +All of the waiters for which the result of the AND is nonzero are woken up; +the remaining waiters are left sleeping. +.IP +The effect of +.B FUTEX_WAIT_BITSET +and +.B FUTEX_WAKE_BITSET +is to allow selective wake-ups among multiple waiters that are blocked +on the same futex. +However, note that, depending on the use case, +employing this bit-mask multiplexing feature on a +futex can be less efficient than simply using multiple futexes, +because employing bit-mask multiplexing requires the kernel +to check all waiters on a futex, +including those that are not interested in being woken up +(i.e., they do not have the relevant bit set in their "wait" bit mask). +.\" According to http://locklessinc.com/articles/futex_cheat_sheet/: +.\" +.\" "The original reason for the addition of these extensions +.\" was to improve the performance of pthread read-write locks +.\" in glibc. However, the pthreads library no longer uses the +.\" same locking algorithm, and these extensions are not used +.\" without the bitset parameter being all ones. +.\" +.\" The page goes on to note that the FUTEX_WAIT_BITSET operation +.\" is nevertheless used (with a bit mask of all ones) in order to +.\" obtain the absolute timeout functionality that is useful +.\" for efficiently implementing Pthreads APIs (which use absolute +.\" timeouts); FUTEX_WAIT provides only relative timeouts. +.IP +The constant +.BR FUTEX_BITSET_MATCH_ANY , +which corresponds to all 32 bits set in the bit mask, can be used as the +.I val3 +argument for +.B FUTEX_WAIT_BITSET +and +.BR FUTEX_WAKE_BITSET . +Other than differences in the handling of the +.I timeout +argument, the +.BR FUTEX_WAIT (2const) +operation is equivalent to +.B FUTEX_WAIT_BITSET +with +.I val3 +specified as +.BR FUTEX_BITSET_MATCH_ANY ; +that is, allow a wake-up by any waker. +The +.BR FUTEX_WAKE (2const) +operation is equivalent to +.B FUTEX_WAKE_BITSET +with +.I val3 +specified as +.BR FUTEX_BITSET_MATCH_ANY ; +that is, wake up any waiter(s). +.\" +.SH RETURN VALUE +On error, +\-1 is returned, +and +.I errno +is set to indicate the error. +.P +The return value on success depends on the operation, +as described in the following list: +.TP +.B FUTEX_WAIT_BITSET +Returns 0 if the caller was woken up. +See +.BR FUTEX_WAIT (2const) +for how to interpret this correctly in practice. +.TP +.B FUTEX_WAKE_BITSET +Returns the number of waiters that were woken up. +.SH ERRORS +See +.BR futex (2). +.TP +.B EAGAIN +.RB ( FUTEX_WAIT_BITSET ) +The value pointed to by +.I uaddr +was not equal to the expected value +.I val +at the time of the call. +.IP +.BR Note : +on Linux, the symbolic names +.B EAGAIN +and +.B EWOULDBLOCK +(both of which appear in different parts of the kernel futex code) +have the same value. +.TP +.B EFAULT +.I timeout +did not point to a valid user-space address. +.TP +.B EINTR +A +.B FUTEX_WAIT_BITSET +operation was interrupted by a signal (see +.BR signal (7)). +Before Linux 2.6.22, this error could also be returned for +a spurious wakeup; since Linux 2.6.22, this no longer happens. +.TP +.B EINVAL +The supplied +.I timeout +argument was invalid +.RI ( tv_sec +was less than zero, or +.I tv_nsec +was not less than 1,000,000,000). +.TP +.B EINVAL +.I uaddr2 +does not point to a valid object\[em]that is, +the address is not four-byte-aligned. +.TP +.B EINVAL +The bit mask supplied in +.I val3 +is zero. +.TP +.B EINVAL +.RB ( FUTEX_WAKE_BITSET ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state\[em]that is, it detected a waiter which waits in +.B FUTEX_LOCK_PI +or +.B FUTEX_LOCK_PI2 +on +.IR uaddr . +.TP +.B ETIMEDOUT +The timeout expired before the operation completed. +.\" +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.25. +.SH SEE ALSO +.BR futex (2)