call_rcu(9)

📦 version 7.3.1, in nixpkgs unstable

✨ call_rcu(9) — like, the whole RCU callback vibe, explained 💅

okay bestie, welcome to the Kernel API Manual page for call_rcu 🎀 this is the one where you queue an RCU callback for invocation after a grace period. and by default?? those callbacks are 'lazy' and get kept hidden from the main ->cblist so grace periods don't start too soon 🙈 if you actually want grace periods to start very very soon, you go use call_rcu_hurry() instead, mwah 💋

🌸 SYNOPSIS 🌸

void call_rcu (struct rcu_head *head , rcu_callback_t func );

🦋 ARGUMENTS 🦋

  • head — the structure you're gonna use for queueing the RCU updates. it's giving "designated parking spot" energy 🅿️✨
  • func — the actual callback function that gets invoked after the grace period. the main character, fr 🫶

💖 DESCRIPTION 💖

so here's the tea ☕ the callback function gets invoked some time after a full grace period elapses — in other words, after all pre-existing RCU read-side critical sections have completed. however 😭 the callback function might well execute concurrently with RCU read-side critical sections that started after call_rcu was invoked. so like, no, it's not a total lockdown, ok?

and listen — it is perfectly legal to repost an RCU callback from within its own callback function, potentially with a different callback function 👑 the specified function will then be invoked after another full grace period has elapsed. this use case is similar in form to the common practice of reposting a timer from within its own handler. very "i'm my own sequel" of it, ngl 💀

RCU read-side critical sections are delimited by rcu_read_lock and rcu_read_unlock, and they may be nested 🪆 in addition — but only in v5.0 and later — regions of code across which interrupts, preemption, or softirqs have been disabled also serve as RCU read-side critical sections. this includes hardware interrupt handlers, softirq handlers, and NMI handlers 🔥

⚠️ okay this next bit is the important one, don't scroll past it ⚠️

note that all CPUs must agree that the grace period extended beyond all pre-existing RCU read-side critical section(s). on systems with more than one CPU, this means that when "func" is invoked, each CPU is guaranteed to have executed a full memory barrier since the end of its last RCU read-side critical section whose beginning preceded the call to call_rcu. phew 😮‍💨

it also means that each CPU executing an RCU read-side critical section that continues beyond the start of "func" must have executed a memory barrier after the call_rcu but before the beginning of that RCU read-side critical section. these guarantees include CPUs that are offline, idle, or executing in user mode, as well as CPUs that are executing in the kernel. literally every CPU, no exceptions, periodt 💅

furthermore 🌈 if CPU A invoked call_rcu and CPU B invoked the resulting RCU callback function "func", then both CPU A and CPU B are guaranteed to execute a full memory barrier during the time interval between the call to call_rcu and the invocation of "func" — even if CPU A and CPU B are the same CPU (but again only if the system has more than one CPU). yes bestie, we said it twice, it's that serious 🙏

implementation of these memory-ordering guarantees is described here:

Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst

🧚 specific to call_rcu (vs the other call_rcu*() girlies) 🧚

in kernels built with CONFIG_RCU_LAZY=y, call_rcu might delay for many seconds before starting the grace period needed by the corresponding callback 😴 this delay can significantly improve energy-efficiency on low-utilization battery-powered devices 🔋✨ which is honestly iconic of it. but to avoid this delay, in latency-sensitive kernel code, use call_rcu_hurry. that's the whole vibe check, iykyk 🫶

👑 SEE ALSO 👑

kernel file ./kernel/rcu/tree.c — plus the whole friend group 💜

🎀 that's the page!! this one came from ./kernel/rcu, dated October 2026, and it's call_rcu(9) from the Kernel API Manual — go queue a callback and slay, bestie 💖✨🍓
📦 where this page comes from