hlist_add_head_rcu(9)

📦 version 7.3.1, in nixpkgs unstable

💅 hlist_add_head_rcu(9) — the Kernel API Manual, bestie edition 🎀

okay so real talk, this one's from the Kernel API Manual (hlist_add_head_rcu(9)) and it's a little niche but honestly kind of iconic once you get it. stay with me 🦋

✨ NAME ✨

So the NAME section? It's literally empty in the source. Like, nothing. Blank. A whole heading with zero vibes. We move on 💀 (no cap, that's genuinely all it gives us).

🌸 SYNOPSIS 🌸

void hlist_add_head_rcu (struct hlist_node *n , struct hlist_head *h );

that's it, that's the whole signature. short king 👑

🎀 ARGUMENTS 🎀

  • n — the element you're adding to the hash list. the main character, fr fr 🫶
  • h — the list you're adding it to. it's giving "the venue" 🏟️

💖 DESCRIPTION 💖

So what this does: it adds the specified element to the specified hlist, while still permitting racing traversals. Yes, "racing" like concurrent, not like cars 🏎️✨

Here's the part you actually need to internalize, bestie:

The caller must take whatever precautions are necessary (such as holding appropriate locks) to avoid racing with another list-mutation primitive, such as hlist_add_head_rcu or hlist_del_rcu, running on this same list.

Translation: if something else is mutating this same list at the same time, that's on you to prevent. Locks, your own discipline, whatever precautions the situation calls for — the function is not doing that for you 🙈

But—and this is the slay part—it is perfectly legal to run concurrently with the _rcu list-traversal primitives, such as hlist_for_each_entry_rcu, which are used to prevent memory-consistency problems on Alpha CPUs. So traversal? concurrent? totally fine. mutation? concurrent? not fine. iykyk 💅

And regardless of the type of CPU, the list-traversal primitive must be guarded by rcu_read_lock. not "should", must. periodt 🔥

🦋 SEE ALSO 🦋

Kernel file ./include/linux/rculist.h, plus the whole friend group right here:

like, the whole squad showed up 🌈✨

👑 the sign-off 👑

this little masterpiece lives in ./include/linux, dated October 2026, and you can find it filed under hlist_add_head_rcu(9) 🍓

that's the whole page, bestie — go forth, lock correctly, and may your traversals always be rcu_read_lock-guarded 💜🧚

📦 where this page comes from