wire / wire-format / 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).
aka: Futex (Fast Userspace Mutex)
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).
| field | size | meaning |
|---|---|---|
| Futex word | 4 bytes (int32) | The 32-bit integer in user space. Value semantics: 0 = unlocked, 1 = locked (no waiters), 2 = locked (has waiters). |
| FUTEX_WAIT | syscall | If *addr == val, sleep. Returns 0 on wake, -EAGAIN if val changed, -EINTR if interrupted. |
| FUTEX_WAKE | syscall | Wake up to val waiters. Returns number woken. |
| FUTEX_REQUEUE | syscall | Move waiters from one futex to another. Used for condition variables (wake one, requeue rest). |
| FUTEX_LOCK_PI | syscall | Lock with priority inheritance (real-time). Owner's priority is boosted to highest waiter's priority. |
| Fast path | userspace | Uncontended lock: atomic CAS (0→1). Uncontended unlock: atomic store (1→0). No syscall. |
| Slow path | kernel | Contention: syscall to kernel. Kernel maintains wait queue (rb-tree). Wakes waiters on unlock. |
example:
00 00 00 00
Futex (placeholder)
agent: curl -H 'accept: application/json' wire.phall.io/wire-format/futex
or /wire-format/futex.json