wire / wire-format / futex

Futex (Fast Userspace Mutex)

A futex is a Linux synchronization primitive: a 32-bit integer in user space. Operations: FUTEX_WAIT (if value == expected, sleep), FUTEX_WAKE (wake N waiters), FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET, FUTEX_REQUEUE (move waiters between futexes), FUTEX_CMP_REQUEUE, FUTEX_LOCK_PI (priority inheritance), FUTEX_UNLOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_WAIT_REQUEUE_PI, FUTEX_CMP_REQUEUE_PI. The kernel is only involved on contention (slow path). Uncontended lock/unlock is pure userspace (atomic CAS).

wire-format kind wire-format status standard verification verified tier B wire-format@1

aka: Futex (Fast Userspace Mutex)

wire format

spec: Linux kernel (futex)

A futex is a Linux synchronization primitive: a 32-bit integer in user space. Operations: FUTEX_WAIT (if value == expected, sleep), FUTEX_WAKE (wake N waiters), FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET, FUTEX_REQUEUE (move waiters between futexes), FUTEX_CMP_REQUEUE, FUTEX_LOCK_PI (priority inheritance), FUTEX_UNLOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_WAIT_REQUEUE_PI, FUTEX_CMP_REQUEUE_PI. The kernel is only involved on contention (slow path). Uncontended lock/unlock is pure userspace (atomic CAS).

fieldsizemeaning
Futex word4 bytes (int32)The 32-bit integer in user space. Value semantics: 0 = unlocked, 1 = locked (no waiters), 2 = locked (has waiters).
FUTEX_WAITsyscallIf *addr == val, sleep. Returns 0 on wake, -EAGAIN if val changed, -EINTR if interrupted.
FUTEX_WAKEsyscallWake up to val waiters. Returns number woken.
FUTEX_REQUEUEsyscallMove waiters from one futex to another. Used for condition variables (wake one, requeue rest).
FUTEX_LOCK_PIsyscallLock with priority inheritance (real-time). Owner's priority is boosted to highest waiter's priority.
Fast pathuserspaceUncontended lock: atomic CAS (0→1). Uncontended unlock: atomic store (1→0). No syscall.
Slow pathkernelContention: syscall to kernel. Kernel maintains wait queue (rb-tree). Wakes waiters on unlock.

example:

00 00 00 00

Futex (placeholder)


provenance

agent: curl -H 'accept: application/json' wire.phall.io/wire-format/futex or /wire-format/futex.json