requeue_pi_wake_futex(9)

💖 NAME 💖

okay so bestie, this is requeue_pi_wake_futex(9) from the Kernel API Manual — and it is literally the page for Wake a task that acquired the lock during requeue. 💅✨

✨ SYNOPSIS ✨

void requeue_pi_wake_futex (struct futex_q *q , union futex_key *key ,
       struct futex_hash_bucket *hb );

🎀 ARGUMENTS 🎀

• q — the futex_q. yep, that one. 🫶
• key — the key of the requeue target futex. 🔑
• hb — the hash_bucket of the requeue target futex. 🪣

🦋 DESCRIPTION 🦋

During futex_requeue, with requeue_pi=1, it is possible to acquire the target futex if it is uncontended or via a lock steal. 🎯 That's the setup, bestie — here's the step-by-step:

1. Set q::key to the requeue target futex key so the waiter can detect the wakeup on the right futex. 👀
2. Dequeue q from the hash bucket. 🧹
3. Set q::rt_waiter to NULL so the woken up task can detect atomic lock acquisition. 💫
4. Set the q->lock_ptr to the requeue target hb->lock for the case that the waiter has to fixup the pi state. 🔧
5. Complete the requeue state so the waiter can make progress. After this point the waiter task can return from the syscall immediately in case that the pi state does not have to be fixed up. 🏃‍♀️
6. Wake the waiter task. 🔔

⚠️ vibe check, and it's serious: Must be called with both q->lock_ptr and hb->lock held. no cap. 💀

🌈 SEE ALSO 🌈

Kernel file ./kernel/futex/requeue.c — also check requeue_futex(9), futex_proxy_trylock_atomic(9), futex_requeue(9), handle_early_requeue_pi_wakeup(9), and futex_wait_requeue_pi(9). 📚💜

okay bye bestie 🫶 — source/version: ./kernel/futex • date: October 2026 • this icon: requeue_pi_wake_futex(9) 💖🌸