futex_proxy_trylock_atomic(9)

📦 version 7.3.1, in nixpkgs unstable

💅 futex_proxy_trylock_atomic(9) 💅

okay so bestie, welcome to the kernel API manual — this one lives in section 9 (the kernel developer zone, iykyk) and it's literally called futex_proxy_trylock_atomic. yes that's a mouthful. no we're not renaming it. it's iconic and we respect it 🫶

✨ NAME ✨

futex_proxy_trylock_atomic — Attempt an atomic lock for the top waiter

like... it tries to grab the lock for the top waiter, atomically. that's the whole vibe check. 🎀

🌸 SYNOPSIS 🌸

int futex_proxy_trylock_atomic (u32 __user *pifutex , struct
futex_hash_bucket *hb1 , struct futex_hash_bucket *hb2 , union futex_key
*key1 , union futex_key *key2 , struct futex_pi_state **ps , struct
task_struct **exiting , int set_waiters );

look at all those parameters. main character energy fr fr. 💅

🦋 ARGUMENTS 🦋

  • pifutex — the user address of the to futex. yep, "the to futex" — that's the wording, we're keeping it, don't come for me 🙈
  • hb1 — the from futex hash bucket, and it must be locked by the caller. not optional. it's giving "you had one job" 💀
  • hb2 — the to futex hash bucket, which also must be locked by the caller. same energy.
  • key1 — the from futex key 🗝️
  • key2 — the to futex key 🗝️
  • ps — address to store the pi_state pointer. it's a pointer to a pointer, we love a double pointer moment ✨
  • exiting — Pointer to store the task pointer of the owner task which is in the middle of exiting. lowkey dramatic but okay 👋
  • set_waiters — force setting the FUTEX_WAITERS bit (1) or not (0). binary queen. either you're setting it or you're not 🌈

💖 DESCRIPTION 💖

So the whole point: Try and get the lock on behalf of the top waiter if we can do it atomically. Wake the top waiter if we succeed. literally "I gotchu bestie, here's the lock, go off 👑".

If the caller specified set_waiters, then it directs futex_lock_pi_atomic to force setting the FUTEX_WAITERS bit. just passing along the instruction, no cap. 🎯

And hb1 and hb2 must be held by the caller. like, both of them. held. by you. before you call this. 🔒

Now the important bit, pay attention: exiting is only set when the return value is -EBUSY. If so, this holds a refcount on the exiting task on return and the caller needs to drop it after waiting for the exit to complete. so if you see -EBUSY, don't just walk away — you're holding a refcount, and you gotta drop it once the exit finishes. it's giving responsibility 💀

🔥 RETURN 🔥

  • 0 — failed to acquire the lock atomically; 😭 no lock for you
  • >0 — acquired the lock, return value is vpid of the top_waiter 🎉 slay
  • <0 — error 💀

🌟 SEE ALSO 🌟

Kernel file ./kernel/futex/requeue.c — plus all these besties:

go read them. iykyk 🧚

⚠️ friendly reminder bestie: hb1 and hb2 must be locked by the caller, and if you get -EBUSY back you are holding a refcount on the exiting task. drop it after waiting for the exit to complete or the vibes will be rancid. fr fr.

and that's the page!! brought to you by ./kernel/futex, dated October 2026 — mwah, ily, go lock something atomically 💜✨🎀

📦 where this page comes from