Ubuntu Manpage: FUTEX_LOCK_PI - lock a priority-inheritance futex

NAME

       FUTEX_LOCK_PI - lock a priority-inheritance futex

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_LOCK_PI, 0,
                    const struct timespec *timeout);

DESCRIPTION

This operation is used after an attempt to acquire the lock via an atomic user-mode instruction failed
because the futex word has a nonzero value—specifically, because it contained the (PID-namespace-
specific) TID of the lock owner.

The operation checks the value of the futex word at the address uaddr. If the value is 0, then the
kernel tries to atomically set the futex value to the caller's TID. If the futex word's value is
nonzero, the kernel atomically sets the FUTEX_WAITERS bit, which signals the futex owner that it cannot
unlock the futex in user space atomically by setting the futex value to 0. After that, the kernel:

(1) Tries to find the thread which is associated with the owner TID.

(2) Creates or reuses kernel state on behalf of the owner. (If this is the first waiter, there is no
kernel state for this futex, so kernel state is created by locking the RT-mutex and the futex owner
is made the owner of the RT-mutex. If there are existing waiters, then the existing state is
reused.)

(3) Attaches the waiter to the futex (i.e., the waiter is enqueued on the RT-mutex waiter list).

If more than one waiter exists, the enqueueing of the waiter is in descending priority order. (For
information on priority ordering, see the discussion of the SCHED_DEADLINE, SCHED_FIFO, and SCHED_RR
scheduling policies in sched(7).) The owner inherits either the waiter's CPU bandwidth (if the waiter is
scheduled under the SCHED_DEADLINE policy) or the waiter's priority (if the waiter is scheduled under the
SCHED_RR or SCHED_FIFO policy). This inheritance follows the lock chain in the case of nested locking
and performs deadlock detection.

The timeout argument provides a timeout for the lock attempt. If timeout is not NULL, the structure it
points to specifies an absolute timeout. If timeout is NULL, the operation will block indefinitely.

RETURN VALUE

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

       On success, FUTEX_LOCK_PI returns 0 if the futex was successfully locked.

ERRORS

       See futex(2).

       EAGAIN The  futex  owner  thread ID of uaddr 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.

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

       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 The kernel detected an inconsistency between the user-space state at uaddr and the  kernel  state.
              This indicates either state corruption or that the kernel found a waiter on uaddr which is waiting
              via FUTEX_WAIT(2const) or FUTEX_WAIT_BITSET(2const).

       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 uaddr.  (This may be caused by a  state
              corruption in user space.)

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

       ETIMEDOUT
              The timeout expired before the operation completed.

STANDARDS

       Linux.

HISTORY

       Linux 2.6.18.

CAVEATS

       Unlike other futex(2) operations, the timeout is measured against the CLOCK_REALTIME clock.