FUTEX_CMP_REQUEUE_PI(2const)

NAME
FUTEX_CMP_REQUEUE_PI - compare a priority-inheritance futex, wake a waiter, and requeue others

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_CMP_REQUEUE_PI, 1,
             uint32_t val2, uint32_t *uaddr2,
             uint32_t val3);

DESCRIPTION
This operation is a PI-aware variant of FUTEX_CMP_REQUEUE(2const). It requeues waiters that are blocked via FUTEX_WAIT_REQUEUE_PI(2const) on uaddr from a non-PI source futex (uaddr) to a PI target futex (uaddr2).

Unlike with FUTEX_CMP_REQUEUE(2const), this operation wakes up a maximum of 1 waiter that is waiting on the futex at uaddr (since the main point is to avoid a thundering herd). The remaining waiters are removed from the wait queue of the source futex at uaddr and added to the wait queue of the target futex at uaddr2.

The val2 and val3 arguments serve the same purposes as for FUTEX_CMP_REQUEUE(2const).

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

On success, FUTEX_CMP_REQUEUE_PI Returns the total number of waiters that were woken up or requeued to the futex for the futex word at uaddr2. If this value is greater than 1, then difference is the number of waiters requeued to the futex for the futex word at uaddr2.

ERRORS
See futex(2).

EAGAIN
    The value pointed to by uaddr is not equal to the expected value val3.

EAGAIN
    The futex owner thread ID of uaddr2 is about to exit, but has not yet handled the internal state cleanup. Try again.

EDEADLK
    The futex word at uaddr is already locked by the caller.

EDEADLK
    While requeueing a waiter to the PI futex for the futex word at uaddr2, the kernel detected a deadlock.

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

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

EINVAL
    uaddr equals uaddr2 (i.e., an attempt was made to requeue to the same futex).

EINVAL
    The kernel detected an inconsistency between the user-space state at uaddr2 and the kernel state; that is, the kernel detected a waiter which waits via FUTEX_WAIT(2const) or FUTEX_WAIT_BITSET(2const) on uaddr2.

EINVAL
    The kernel detected an inconsistency between the user-space state at uaddr and the kernel state; that is, the kernel detected a waiter which waits via FUTEX_WAIT(2const) or FUTEX_WAIT_BITSET(2const) on uaddr.

EINVAL
    The kernel detected an inconsistency between the user-space state at uaddr and the kernel state; that is, the kernel detected a waiter which waits on uaddr via FUTEX_LOCK_PI(2const) or FUTEX_LOCK_PI2(2const) (instead of FUTEX_WAIT_REQUEUE_PI).

EINVAL
    An attempt was made to requeue a waiter to a futex other than that specified by the matching FUTEX_WAIT_REQUEUE_PI call for that waiter.

EINVAL
    The fourth argument is not 1.

ENOMEM
    The kernel could not allocate memory to hold state information.

ENOSYS
    A run-time check determined that the operation is not available. The PI-futex operations are not implemented on all architectures and are not supported on some CPU variants.

EPERM
    The caller is not allowed to attach itself to the futex at uaddr2. (This may be caused by a state corruption in user space.)

ESRCH
    The thread ID in the futex word at uaddr does not exist.

ESRCH
    The thread ID in the futex word at uaddr2 does not exist.

STANDARDS
Linux.

HISTORY
Linux 2.6.31.

SEE ALSO
futex(2)