RCU_INIT_POINTER(9)

📦 version 7.3.1, in nixpkgs unstable

💅 RCU_INIT_POINTER(9) — the kernel API manual, bestie edition 🎀

Okay so this is a page from the Kernel API Manual and it's about RCU_INIT_POINTER, which initializes an RCU protected pointer. Sounds chill, is actually lowkey a loaded gun, but we'll get there ✨

🌸 NAME 🌸

RCU_INIT_POINTER — initialize an RCU protected pointer 🫶

⭐ SYNOPSIS ⭐

RCU_INIT_POINTER (p , v );

That's the whole vibe. Two args, one function, zero ordering guarantees (we'll circle back to that, iykyk 👀).

🦋 ARGUMENTS 🦋

  • p — the pointer that's getting initialized. the main character of this whole operation 💖
  • v — the value you're initializing that pointer to. the supporting actress, but make it iconic 💅

🔥 DESCRIPTION 🔥

So here's the tea: you use RCU_INIT_POINTER to initialize an RCU-protected pointer in those special cases where readers genuinely do not need ordering constraints — not on the CPU, not on the compiler. None. Nada. 🧚

And the special cases are, like, extremely specific. Here's the list, no cap:

  1. This use of RCU_INIT_POINTER is NULLing out the pointer or
  2. The caller has taken whatever steps are required to prevent RCU readers from concurrently accessing this pointer or
  3. The referenced data structure has already been exposed to readers either at compile time or via rcu_assign_pointer and
    • a. You have not made any reader-visible changes to this structure since then or
    • b. It is OK for readers accessing this structure from its new location to see the old state of the structure. (For example, the changes were to statistical counters or to other state where exact synchronization is not required.)

That's it. That's the whole checklist. You either tick one of those three boxes, or you don't get to use this function. Periodt. 🎯

⚠️ Okay so listen, and I mean really listen: failure to follow these rules governing use of RCU_INIT_POINTER will result in impossible-to-diagnose memory corruption. Like… literally impossible. As in the structures will look OK in crash dumps, but any concurrent RCU readers might see pre-initialized values of the referenced data structure. 💀 So please be very careful how you use RCU_INIT_POINTER!!! This is not a drill, bestie 😭

Now for the cute little extra scenario 🌈 — if you are creating an RCU-protected linked structure that is accessed by a single external-to-structure RCU-protected pointer, then you may use RCU_INIT_POINTER to initialize the internal RCU-protected pointers. But! You must use rcu_assign_pointer to initialize the external-to-structure pointer after you have completely initialized the reader-accessible portions of the linked structure. Order matters, bestie. Read the room. Then read the order. 👑

And finally, the note that everyone skips and shouldn't: note that unlike rcu_assign_pointer, RCU_INIT_POINTER provides no ordering guarantees for either the CPU or the compiler. Like, none. Zero. It is not giving ordering. It is giving "you're on your own, queen" 💀✨

🍓 SEE ALSO 🍓

Kernel file ./include/linux/rcupdate.h, plus a whole friend group of related pages — same_state_synchronize_rcu(9), cond_resched_tasks_rcu_qs(9), rcu_softirq_qs_periodic(9), RCU_LOCKDEP_WARN(9), lockdep_assert_in_rcu_read_lock(9), lockdep_assert_in_rcu_read_lock_bh(9), lockdep_assert_in_rcu_read_lock_sched(9), lockdep_assert_in_rcu_reader(9), unrcu_pointer(9), RCU_INITIALIZER(9), rcu_assign_pointer(9), rcu_replace_pointer(9), rcu_access_pointer(9), rcu_dereference_check(9), rcu_dereference_bh_check(9), rcu_dereference_sched_check(9), rcu_dereference_all_check(9), rcu_dereference_protected(9), rcu_dereference(9), rcu_dereference_bh(9), rcu_dereference_sched(9), rcu_dereference_all(9), rcu_pointer_handoff(9), rcu_read_lock(9), rcu_read_unlock(9), rcu_read_lock_bh(9), rcu_read_unlock_bh(9), rcu_read_lock_sched(9), rcu_read_unlock_sched(9), RCU_POINTER_INITIALIZER(9), kfree_rcu(9), kfree_rcu_mightsleep(9), kfree_rcu_nolock(9), rcu_head_init(9), rcu_head_after_call_rcu(9) — go read them, they're all slay 💜

and that's the whole page, bestie 🫶 it lives in ./include/linux and this version is dated October 2026, brought to you by the fine folks maintaining the kernel API manual. mwah 💋 go forth and initialize responsibly ✨🎀

📦 where this page comes from