Ubuntu Manpage: FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET - selective futex waiting and waking

NAME

       FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET - selective futex waiting and waking

LIBRARY

       Standard C library (libc, -lc)

SYNOPSIS

       #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);

DESCRIPTION

FUTEX_WAIT_BITSET
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.

FUTEX_WAKE_BITSET
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).

RETURN VALUE

       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:

       FUTEX_WAIT_BITSET
              Returns  0 if the caller was woken up.  See FUTEX_WAIT(2const) for how to interpret this correctly
              in practice.

       FUTEX_WAKE_BITSET
              Returns the number of waiters that were woken up.

ERRORS

       See futex(2).

       EAGAIN (FUTEX_WAIT_BITSET) The value pointed to by uaddr was not equal to the expected value val  at  the
              time of the call.

              Note: on Linux, the symbolic names EAGAIN and EWOULDBLOCK (both of which appear in different parts
              of the kernel futex code) have the same value.

       EFAULT timeout did not point to a valid user-space address.

       EINTR  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.

       EINVAL The supplied timeout argument was invalid (tv_sec was less than zero, or tv_nsec was not less than
              1,000,000,000).

       EINVAL uaddr2 does not point to a valid object—that is, the address is not four-byte-aligned.

       EINVAL The bit mask supplied in val3 is zero.

       EINVAL (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.

       ETIMEDOUT
              The timeout expired before the operation completed.

STANDARDS

       Linux.

HISTORY

       Linux 2.6.25.