FUTEX_CMP_REQUEUE(2const)

💖 FUTEX_CMP_REQUEUE 💖

okay so bestie, listen — this is the futex op that checks a value, wakes a couple of people, and then rehomes the rest. it's giving bouncer-at-the-club energy and honestly? iconic. 🌈

part of the Linux family, and this page is FUTEX_CMP_REQUEUE(2const).

---

📚 LIBRARY

Standard C library (libc, -lc). yeah she lives in libc, come through. ✨

---

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

like yes we're raw-dogging syscall(2) because that's just how futexes are, no wrapper, no cap. 🫶

---

✨ DESCRIPTION ✨

so the ✨vibe check✨ happens first: this operation checks whether the location uaddr still contains the value val3. if it does not, the operation fails with the error EAGAIN. no vibes, no service. 💀

otherwise? we wake up a maximum of val waiters that are waiting on the futex at uaddr. and if there are more than val waiters — because bestie, there are always more — then the remaining waiters get removed from the wait queue of the source futex at uaddr and added to the wait queue of the target futex at uaddr2. glow-up relocation, honestly. 🌸

and the val2 argument? that's the upper limit on how many waiters get requeued over to the futex at uaddr2. it's the "no more than this many, i beg" number.

now, the load from uaddr is an atomic memory access (i.e., using atomic machine instructions of the respective architecture — she's built different at the silicon level). and this load, the comparison with val3, and the requeueing of any waiters are all performed atomically and totally ordered with respect to other operations on the same futex word. periodt. 👑

typical values to specify for val are 0 or 1. (specifying val as INT_MAX is not useful, because it would make the FUTEX_CMP_REQUEUE operation equivalent to FUTEX_WAKE(2const).) the limit value specified via val2 is typically either 1 or INT_MAX. (specifying val2 as 0 is not useful, because it would make the FUTEX_CMP_REQUEUE operation equivalent to FUTEX_WAKE(2const).)

---

🦋 the lore: why she exists

the FUTEX_CMP_REQUEUE operation was added as a replacement for the earlier FUTEX_REQUEUE(2const). the difference? the check of the value at uaddr can be used to ensure that requeueing happens only under certain conditions, which allows race conditions to be avoided in certain use cases. that's the whole upgrade bestie, and it ate. 💅

both FUTEX_REQUEUE(2const) and FUTEX_CMP_REQUEUE can be used to avoid "thundering herd" wake-ups that could occur when using FUTEX_WAKE(2const) in cases where all of the waiters that are woken need to acquire another futex. 😭 imagine waking everyone and they all just pile back up. tragic.

consider the following scenario, where multiple waiter threads are waiting on B, a wait queue implemented using a futex:

lock(A)
while (!check_value(V)) {
    unlock(A);
    block_on(B);
    lock(A);
};
unlock(A);

if a waker thread used FUTEX_WAKE(2const), then all waiters waiting on B would be woken up, and they would all try to acquire lock A. however, waking all of the threads in this manner would be pointless because all except one of the threads would immediately block on lock A again. like… okay?? why did we even. 🙈

by contrast, a requeue operation wakes just one waiter and moves the other waiters to lock A, and when the woken waiter unlocks A then the next waiter can proceed. efficient. orderly. main character energy. ⭐

---

🌟 RETURN VALUE

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

on success, FUTEX_CMP_REQUEUE returns the total number of waiters that were woken up or requeued to the futex for the futex word at uaddr2. and if this value is greater than val, then the difference is the number of waiters requeued to the futex for the futex word at uaddr2. math is mathing. 🧮

---

💀 ERRORS

see futex(2).

• EAGAIN — the value pointed to by uaddr is not equal to the expected value val3. (vibe check failed, sorry babe.)
• 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. alignment girlies stay winning.
• EINVAL — the kernel detected an inconsistency between the user-space state at uaddr and the kernel state—that is, it detected a waiter which waits in FUTEX_LOCK_PI(2const) or FUTEX_LOCK_PI2(2const) on uaddr.

---

🏳️🌈 STANDARDS

Linux. that's it, that's the line. 💜

---

📜 HISTORY

Linux 2.6.7. she's been around, she's vintage, she's still relevant. 👑

---

👀 SEE ALSO

• futex(2)

---

lowkey a warning but make it cute: those EINVAL cases are real and they will find you, so double-check your alignment and your state consistency before you go blaming the kernel. 🫶

---

mwah 💖 this page came to you courtesy of Linux man-pages 6.20, dated 2025-09-21 — go forth and requeue responsibly, bestie. 🎀✨