LOCKLESS QUEUE STOPPING WAKING HELPERS.(9)

💅 LOCKLESS QUEUE STOPPING / WAKING HELPERS (9) 💅

okay bestie so this is a page straight out of the Kernel API Manual, and it's all about the lockless queue stopping / waking helpers — yes the title is literally "Lockless queue stopping / waking helpers" and no we are not shortening it, it's iconic 😌

---

✨ DESCRIPTION ✨

so the two macros we're obsessing over are netif_txq_maybe_stop and __netif_txq_completed_wake, and what they do is let you safely implement stopping and waking of netdev queues without full lock protection. no locks, no drama, we love to see it 🫶

here's the vibe check on the assumptions, and this part is important so pay attention:

• we assume there can be no concurrent stop attempts and no concurrent wake attempts ✋
• the try-stop should happen from the xmit handler, while wake up should be triggered from NAPI poll context
• those two may run concurrently — it's giving single producer, single consumer energy 💫

---

🌸 THE TRY-STOP SIDE vs THE WAKING SIDE 🌸

the try-stop side is expected to run from the xmit handler, and because of that it does not reschedule Tx — it uses netif_tx_start_queue instead of netif_tx_wake_queue. periodt. 💅

⚠️ using the stop macros outside of the xmit handler may lead to the xmit queue being enabled but not run 😭 so like, don't do that.

the waking side though? it does not have those same context restrictions. she's free, she's flexible, she's unbothered 🦋

---

🎀 THE BIG CAVEAT (read this fr fr) 🎀

the macros guarantee that rings will not remain stopped if there's space available — slay ✅

but they do not prevent false wake ups when the ring is full! 💀 so drivers should check for ring full at the start for the xmit handler. no cap, that's on you.

one more thing bestie, and it's non-negotiable: all descriptor ring indexes (and other relevant shared state) must be updated before invoking the macros. like, before. not during, not after. before. 👑

---

🔥 SEE ALSO 🔥

• the kernel file ./include/net/netdev_queues.h, plus struct netdev_config(9)
• struct netdev_stat_ops(9)
• struct netdev_queue_mgmt_ops(9)
• netif_txq_maybe_stop(9)
• __netif_txq_completed_wake(9)

go read them, iykyk 📚✨

---

k BYE this page came from ./include/net, dated October 2026, and it lives under the Lockless queue stopping / waking helpers.(9) title 🎀💖 mwah, go stop some queues safely 🧚‍♀️