Ubuntu Manpages

FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET

selective futex waiting and waking

Standard C library (libc, -lc)

#include <linux/futex.h>  /* Definition of FUTEX_* constants */
#include <sys/syscall.h>  /* Definition of SYS_* constants */
#include <unistd.h>
long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAIT_BITSET, uint32_t val,
             const struct timespec *timeout, NULL,
             uint32_t val3);
long syscall(SYS_futex, uint32_t *uaddr, FUTEX_WAKE_BITSET, uint32_t val,
             NULL, NULL,
             uint32_t val3);

This operation is like FUTEX_WAIT(2const) except that 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 FUTEX_WAKE_BITSET for further details.
If timeout is not NULL, the structure it points to specifies an absolute timeout for the wait operation. If timeout is NULL, the operation can block indefinitely.
This operation is the same as FUTEX_WAKE(2const) except that the 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 val3) and the bit mask which is stored in the kernel-internal state of the waiter (the "wait" bit mask that is set using 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.
The effect of FUTEX_WAIT_BITSET and 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).
The constant FUTEX_BITSET_MATCH_ANY, which corresponds to all 32 bits set in the bit mask, can be used as the val3 argument for FUTEX_WAIT_BITSET and FUTEX_WAKE_BITSET. Other than differences in the handling of the timeout argument, the FUTEX_WAIT(2const) operation is equivalent to FUTEX_WAIT_BITSET with val3 specified as FUTEX_BITSET_MATCH_ANY; that is, allow a wake-up by any waker. The FUTEX_WAKE(2const) operation is equivalent to FUTEX_WAKE_BITSET with val3 specified as FUTEX_BITSET_MATCH_ANY; that is, wake up any waiter(s).

On error, -1 is returned, and errno is set to indicate the error.

The return value on success depends on the operation, as described in the following list:

Returns 0 if the caller was woken up. See FUTEX_WAIT(2const) for how to interpret this correctly in practice.
Returns the number of waiters that were woken up.

See futex(2).

(FUTEX_WAIT_BITSET) The value pointed to by uaddr was not equal to the expected value val at the time of the call.
timeout did not point to a valid user-space address.
A FUTEX_WAIT_BITSET operation was interrupted by a signal (see 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.
The supplied timeout argument was invalid (tv_sec was less than zero, or tv_nsec was not less than 1,000,000,000).
uaddr2 does not point to a valid object—that is, the address is not four-byte-aligned.
The bit mask supplied in val3 is zero.
(FUTEX_WAKE_BITSET) The kernel detected an inconsistency between the user-space state at uaddr and the kernel state—that is, it detected a waiter which waits in FUTEX_LOCK_PI(2const) or FUTEX_LOCK_PI2(2const) on uaddr.
The timeout expired before the operation completed.

Linux.

Linux 2.6.25.

futex(2)