rhashtable_next_key(9)

📦 version 7.3.1, in nixpkgs unstable

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

okay so you found the rhashtable_next_key(9) page in the Kernel API Manual and you're like "what is this" — don't worry, I got you, we're gonna read it together and it's gonna slay ✨

🌸 NAME 🌸

rhashtable_next_key — returns the next element after a given key, literally that's the whole vibe 🦋

✨ SYNOPSIS ✨

void * rhashtable_next_key (struct rhashtable *ht , const void *prev_key );

like, that's it. that's the signature. iconic 👑

🫶 ARGUMENTS 🫶

  • ht — the hash table. the main character, the table in question 💖
  • prev_key — pointer to the previous key, or NULL for the first element. so if you're passing NULL, you're basically saying "start me from the top bestie" 🌈

🔥 DESCRIPTION 🔥

⚠️ WARNING: this walk is highly unstable. like, unhinged levels of unstable, no cap. Unlike rhashtable_walk_*(), it cannot detect a concurrent resize or rehash, so a full iteration is NOT guaranteed to terminate under adversarial or sustained rehashing. You, the caller, MUST tolerate skipped and duplicated elements and SHOULD bound your loop externally. this is not a drill, fr fr 💀

so what does it actually do? it returns the next element in best-effort iteration order, walking the tbl chain (including any future_tbl in flight). caller must hold RCU. that part is non-negotiable, bestie 🫡

Pass prev_key == NULL to obtain the first element. To iterate, set prev_key to the key of the previously returned element on each call, and stop when NULL is returned. cute, simple loop energy 🌸

💅 Best-effort semantics 💅

this is the part where you sit down and pay attention, because the vibes are best-effort and bestie, best-effort is a whole personality:

  • Across the tbl->future_tbl chain, an element being migrated may transiently appear in both tables and be observed twice. yes, twice. it's giving "she's in her migration era" 🙈
  • Concurrent inserts may or may not be observed. literally may. or may not. no promises were made 🦋
  • Termination of a full iteration loop is NOT guaranteed under adversarial continuous rehash; callers MUST tolerate skips and repeats and SHOULD bound their loop externally. read that again. bound your loop. do it for me 😭
  • Behavior on tables that contain duplicate keys is undefined: duplicates may be skipped, repeated, or trap the walk in a cycle. the way your walk could just... get stuck in a cycle forever 💀 callers requiring duplicate-key iteration must use rhashtable_walk_*() instead. that's the supported path, periodt 👑
  • rhltable instances are not supported and return ERR_PTR(-EOPNOTSUPP). not supported, not invited, not on the list 🙅‍♀️
  • If prev_key was concurrently deleted and is not present in any in-flight table, returns ERR_PTR(-ENOENT). she's gone, bestie, she left the chat 💨

so the return value situation is: entry of the next element, or NULL when iteration is exhausted, or ERR_PTR(-ENOENT) if prev_key is not found, or ERR_PTR(-EOPNOTSUPP) if ht is an rhltable. three error-ish outcomes, one success, and a partridge in a pear tree 🍓

🌈 SEE ALSO 🌈

Kernel file ./lib/rhashtable.c and honestly the whole walk squad — go read these, they're the friend group:

and that's the page, bestie 🎀 this little baby lives at ./lib, dated October 2026, and it's filed under rhashtable_next_key(9) — go forth, hold RCU, bound your loops, and don't say I didn't warn you 💖✨

📦 where this page comes from