STRUCT FUTEX_Q(9)

💅 struct futex_q(9)

okay bestie, buckle up — this is a page from the Kernel API Manual, and it's about struct futex_q, which is the hashed futex queue entry, one per waiting task. literally one for every task that's waiting. iconic behavior tbh 🎀

---

✨ NAME ✨

struct futex_q — the hashed futex queue entry, one per waiting task 🦋

---

🧚 SYNOPSIS 🧚

struct futex_q {
    struct plist_node list;
    struct task_struct *task;
    spinlock_t *lock_ptr;
    futex_wake_fn *wake;
    void *wake_data;
    union futex_key key;
    struct futex_pi_state *pi_state;
    struct rt_mutex_waiter *rt_waiter;
    union futex_key *requeue_pi_key;
    u32 bitset;
    atomic_t requeue_state;
    struct futex_private_hash *drop_fph;
  #ifdef CONFIG_PREEMPT_RT;
    struct rcuwait requeue_wait;
  #endif;
 };

like, that's the whole shape of it. every field accounted for, no notes 💅

---

🌸 Members 🌸

okay so here's the cast of characters, one by one, no skips:

• list — priority-sorted list of tasks waiting on this futex. yes, sorted, it's giving organized queen energy 👑
• task — the task waiting on the futex. the main character of this entry ngl
• lock_ptr — the hash bucket lock 🔒
• wake — the wake handler for this queue
• wake_data — data associated with the wake handler. it's the handler's little plus-one 🫶
• key — the key the futex is hashed on
• pi_state — optional priority inheritance state. optional! it's giving only if you're that girl ✨
• rt_waiter — rt_waiter storage for use with requeue_pi
• requeue_pi_key — the requeue_pi target futex key
• bitset — bitset for the optional bitmasked wakeup
• requeue_state — State field for futex_requeue_pi
• drop_fph — Waiter should drop the extra private hash reference when set
• requeue_wait — RCU wait for futex_requeue_pi (RT only) ⏳

---

💖 Description 💖

so like, why does this even exist? We use this hashed waitqueue, instead of a normal wait_queue_entry_t, so we can wake only the relevant ones (hashed queues may be shared). lowkey a flex, but a necessary one — no cap 💀

A futex_q has a woken state, just like tasks have TASK_RUNNING. It is considered woken when:

plist_node_empty(q->list) || q->lock_ptr == 0

and the order of wakeup is always to make the first condition true, then the second. don't flip them, bestie, that's the whole ritual 🕯️

PI futexes are typically woken before they are removed from the hash list via the rt_mutex code. see futex_unqueue_pi. 🦋

---

🔥 SEE ALSO 🔥

Kernel file ./kernel/futex/futex.h futex_match(9), futex_queue(9), struct futex_vector(9) — go read those next, iykyk 💜

---

okay that's the whole page, mwah 💋 this one lives in ./kernel/futex, dated October 2026 — shoutout to that directory for keeping it real, and to the Kernel API Manual for the hosting gig 🎀✨