Ubuntu Manpages

FUTEX_LOCK_PI

lock a priority-inheritance futex

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

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.

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.

See futex(2).

The futex owner thread ID of uaddr is about to exit, but has not yet handled the internal state cleanup. Try again.
The futex word at uaddr is already locked by the caller.
timeout did not point to a valid user-space address.
The supplied timeout argument was invalid (tv_sec was less than zero, or tv_nsec was not less than 1,000,000,000).
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).
The kernel could not allocate memory to hold state information.
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.
The caller is not allowed to attach itself to the futex at uaddr. (This may be caused by a state corruption in user space.)
The thread ID in the futex word at uaddr does not exist.
The timeout expired before the operation completed.

Linux.

Linux 2.6.18.

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

futex(2)