RADIX-TREE SYNCHRONIZATION(9)

✨ RADIX-TREE SYNCHRONIZATION ✨

okay so bestie, welcome to Radix-tree synchronization(9) from the Kernel API Manual — yes we're doing kernel internals today and honestly the way this whole page is structured?? obsessed 💅

🫶 the vibe check

The radix-tree API is extremely clear about one thing: you provide all synchronisation. Not the API, not the tree, not some helpful little helper. You. (With specific exceptions, noted below — we'll get there, don't spiral 🌸)

Also management of lifetimes? That's yours too. Synchronization of access to the data items being stored in the tree, and management of their lifetimes must be completely managed by API users. Periodt.

For API usage, in general:

• any function _modifying_ the tree or tags (inserting or deleting items, setting or clearing tags) must exclude other modifications, and exclude any functions reading the tree 🔥
• any function _reading_ the tree or tags (looking up items or tags, gang lookups) must exclude modifications to the tree, but may occur concurrently with other readers ⭐

🎀 the exceptions (the iconic ones)

The notable exceptions to this rule are the following functions:

• __radix_tree_lookup
• radix_tree_lookup
• radix_tree_lookup_slot
• radix_tree_tag_get
• radix_tree_gang_lookup
• radix_tree_gang_lookup_tag
• radix_tree_gang_lookup_tag_slot
• radix_tree_tagged

The first 7 functions are able to be called locklessly, using RCU 😤 The caller must ensure calls to these functions are made within rcu_read_lock regions. Other readers (lock-free or otherwise) and modifications may be running concurrently.

It is still required that the caller manage the synchronization and lifetimes of the items 🫶 So if RCU lock-free lookups are used, typically this would mean that the items have their own locks, or are amenable to lock-free access; and that the items are freed by RCU (or only freed after having been deleted from the radix tree and a synchronize_rcu grace period).

💀 lowkey important footnote: rcu_assign_pointer and rcu_dereference are not needed to control access to data items when inserting into or looking up from the radix tree.

😭 the radix_tree_tag_get situation (read this one fr fr)

Note that the value returned by radix_tree_tag_get may not be relied upon if only the RCU read lock is held. Functions to set/clear tags and to delete nodes running concurrently with it may affect its result such that two consecutive reads in the same locked section may return different values 🙈

So like… don't trust it blindly. If reliability is required, modification functions must also be excluded from concurrency. That's the whole deal, no cap.

👑 and one chill one

radix_tree_tagged is able to be called without locking or RCU. No locks, no RCU, no stress. Iconic behaviour honestly 🌈

---

🌈 SEE ALSO 🌈

• Kernel file ./include/linux/radix-tree.h
• struct radix_tree_iter(9)
• radix_tree_deref_slot(9)
• radix_tree_deref_slot_protected(9)
• radix_tree_deref_retry(9)
• radix_tree_exception(9)
• radix_tree_iter_init(9)
• radix_tree_next_chunk(9)
• radix_tree_iter_lookup(9)
• radix_tree_iter_retry(9)
• radix_tree_iter_resume(9)
• radix_tree_chunk_size(9)
• radix_tree_next_slot(9)
• radix_tree_for_each_slot(9)
• radix_tree_for_each_tagged(9)

---

that's the whole page bestie, go forth and lock correctly 🧚💖 — source ./include/linux, dated October 2026, and it's Radix-tree synchronization(9) all the way down. mwah 🎀