Honestly, the first time I saw RefCell, I almost closed my laptop.
Rust claims to be “safe first,” immutable by default, right? Then suddenly this thing shows up saying “hey, we can modify data through an immutable reference.” Isn’t that exactly what Rust spent so much effort preventing?
My brain was full of questions: Isn’t this the opposite of what Rust is supposed to prevent?
But later, when I really understood what problem it was solving, I realized how brilliant this design actually is.
Today let’s talk about this feature that drove me crazy then enlightened me.
What is RefCell? A Room with Keycard Access
Think of RefCell as a room with a keycard access system. This room has a special rule: on the surface, it looks “read-only”—anyone can enter and look around. But if you have the keycard, you can change things inside once you’re in.
This “keycard system” is RefCell’s runtime borrow checking. Let me illustrate:
Normal Rust (compile-time check):
┌─────────┐ ┌─────────────┐
│ var x │────▶│ value: 10 │ ← immutable &x
└─────────┘ └─────────────┘
▲
│
Want to change to 20? ❌
Compiler blocks you immediately!
With RefCell (runtime check):
┌─────────┐ ┌─────────────────────────┐
│ var x │────▶│ RefCell │ value: 10│ ← borrow_mut() can change
└─────────┘ └─────────────────────────┘
▲
│
Keycard ✓
Runtime check passes → change to 20
Normally, Rust’s borrowing rules are checked at compile time:
// This won't work
let x = 10;
let y = &x; // immutable reference
*y = 20; // Compiler error: can't assign through immutable reference
But RefCell defers this check to runtime:
use std::cell::RefCell;
fn main() {
let value = RefCell::new(10);
*value.borrow_mut() = 20; // Runtime check, if it passes then change
println!("Value: {}", value.borrow());
}
What does this mean? It means Rust watches you at runtime, ensuring you don’t hold both mutable and immutable references simultaneously. If you violate the rules, your program panics—but this panic happens at runtime, not compile time.
Why Do We Need This?
I encountered RefCell while building a plugin system. Each plugin could depend on other plugins, forming a dependency graph. The problem was: each plugin needed references to other plugins, but also needed to modify its own state.
The naive approach looked something like this:
struct Plugin {
name: String,
dependencies: Vec<&Plugin>, // references to other plugins
active: bool,
}
The compiler immediately throws an error: “borrowed value does not live long enough.”
This is the limitation of Rust’s borrow checker. It can’t express “shared ownership with mutable inner state” at compile time.
That’s when Rc<RefCell
Rc + RefCell: The Golden Pair
Rc handles shared ownership, RefCell handles interior mutability. Together, they solve our problem.
First, let’s look at the structure:
How Rc<RefCell<T>> works:
┌──────────────────┐
┌────────│ Rc<T> (ref count) │────────┐
│ └──────────────────┘ │
│ │
Owner A Owner B
│ │
└──────────┬─────────────┬───────────┘
▼ ▼
┌──────────────────────────┐
│ RefCell<T> │
│ ┌──────────────────┐ │
│ │ borrow flag │ │ ← runtime borrow check
│ │ 0=free 1=borrow │ │
│ └──────────────────┘ │
│ ┌──────────────────┐ │
│ │ data T │ │
│ └──────────────────┘ │
└──────────────────────────┘
Complete code:
use std::cell::RefCell;
use std::rc::Rc;
// Type alias for convenience
type PluginRef = Rc<RefCell<Plugin>>;
struct Plugin {
name: String,
dependencies: Vec<PluginRef>,
active: bool,
}
impl Plugin {
fn new(name: &str) -> PluginRef {
Rc::new(RefCell::new(Self {
name: name.to_string(),
dependencies: Vec::new(),
active: false,
}))
}
fn activate(&mut self) {
self.active = true;
println!("{} activated!", self.name);
}
}
Now you can easily create plugin dependencies:
fn main() {
let plugin_a = Plugin::new("Core");
let plugin_b = Plugin::new("UI");
// UI plugin depends on Core
plugin_b.borrow_mut().dependencies.push(plugin_a.clone());
// Activate Core
plugin_a.borrow_mut().activate();
// Print dependency
println!(
"{} depends on {}",
plugin_b.borrow().name,
plugin_b.borrow().dependencies[0].borrow().name
);
}
Dependency graph:
Plugin Dependency Graph:
┌─────────────┐
│ Core │ ◀───────┐
│ (plugin_a) │ │
└─────────────┘ │
│ │
│ depends │ owns (Rc)
▼ │
┌─────────────┐ │
│ UI │ ────────┘
│ (plugin_b) │
└─────────────┘
Rc lets both plugins hold each other,
RefCell lets them modify inner state when needed
This code runs smoothly. Rc allows multiple places to own the plugin simultaneously, while RefCell lets those owners modify the plugin’s state when needed.
RefCell’s Borrow Flag: The Runtime Gatekeeper
Inside RefCell is a “borrow flag” that acts like a gatekeeper:
RefCell Internal State:
┌─────────────────────────────────┐
│ RefCell<T> │
│ │
│ borrow_flag: │
│ ┌─────┬─────┬─────┬─────┐ │
│ │ 0 │ 1 │ 2 │ ... │ │
│ │free │r1 │r2 │rN │ │
│ └─────┴─────┴─────┴─────┘ │
│ │ │
│ │ -1 = write exclusive │
│ │
│ ┌───────────────────────┐ │
│ │ data T │ │
│ └───────────────────────┘ │
└─────────────────────────────────┘
borrow() → flag+1 (read lock)
borrow_mut() → flag=-1 (write lock)
drop() → restore
When you call borrow() or borrow_mut(), RefCell checks this flag:
// These operations are safe
let r1 = refcell.borrow(); // flag: 0 → 1 (start reading)
let r2 = refcell.borrow(); // flag: 1 → 2 (continue reading)
drop(r1); // flag: 2 → 1 (end one read)
drop(r2); // flag: 1 → 0 (all done)
// These will panic
let r1 = refcell.borrow(); // flag: 0 → 1 (start reading)
let w1 = refcell.borrow_mut(); // panic! already being read
let w1 = refcell.borrow_mut(); // flag: 0 → -1 (start writing)
let w2 = refcell.borrow_mut(); // panic! already being written
What’s the Cost of Runtime Checking?
There’s no free lunch—RefCell’s flexibility comes with a cost.
Someone did benchmarks comparing direct modification, RefCell modification, and Rc
| Operation | Time (ns) | Relative |
|---|---|---|
| Direct | 1.0 | 1x |
| RefCell borrow_mut | 13.5 | ~13x |
| Rc | 21.0 | ~21x |
Performance comparison (nanosecond level):
Direct: ███ 1.0ns
RefCell: ████████████████████ 13.5ns
Rc+RefCell: █████████████████████████████ 21.0ns
Looks like a big gap, but remember: this is nanoseconds!
Most of your code's time isn't spent on these operations
Looks scary, but think about it: this is nanosecond-level difference. In most real applications, this overhead is completely negligible. If you’re calling borrow_mut frequently in a tight loop, that’s probably a design problem, not RefCell’s problem.
I learned a lesson the hard way: when using RefCell, I accidentally created circular dependencies—Plugin A depends on B, B depends on A. This triggered borrow errors at runtime and the program panicked:
Danger of Circular Dependencies:
┌─────────┐ ┌─────────┐
│ Plugin A│◄────────│ Plugin B│
└─────────┘ └─────────┘
│ │
└──────┬────────────┘
│
(Rc<RefCell>)
│
▼
Potential memory leak!
Need to use Weak to break cycles
But this panic made me realize: RefCell gives you flexibility, not freedom. You still need to design your logic carefully.
RefCell Doesn’t Break Rules, It Completes Them
After understanding RefCell, my biggest realization was: it’s not breaking Rust’s rules, it’s completing them.
Rust's Safety Strategy:
Compile-time Check
┌─────────────────────┐
│ Static Analysis │ ← Most cases
│ (Borrow Checker) │
└─────────────────────┘
│
│ Can't express?
▼
┌─────────────────────┐
│ Runtime Check │ ← RefCell/Mutex
│ (Dynamic Borrow) │
└─────────────────────┘
Some scenarios can’t be expressed with static compile-time checks, but can with dynamic runtime checks. RefCell is the bridge between these two. It lets you write more flexible, dynamic architectures while maintaining Rust’s safety guarantees.
The borrow checker is like a wall—RefCell is the door in that wall. You need the right key to open it, but with that door, you can reach places that were previously inaccessible.
The Borrow Checker Wall:
❌ Compile-time check fails
┌─────────────────────────────┐
│ │
│ ╔═══════════════════════╗ │
│ ║ Rust Borrow Checker ║ │
│ ║ (The Wall) ║ │
│ ╠═══════════════════════╣ │
│ ║ ║ │
│ ║ [🚪 RefCell] ║ │ ← Backdoor
│ ║ (runtime check) ║ │
│ ║ ║ │
│ ╚═══════════════════════╝ │
│ │
└─────────────────────────────┘
│
▼
✅ Passes at runtime
Summary
RefCell does something simple: it moves borrow checking from compile time to runtime, letting you modify inner state with shared ownership.
Remember these points when using it:
- Runtime check means violations panic at runtime, not compile time
- Use with Rc to solve shared mutable state problems
- Performance overhead is nanosecond-level, don’t worry in practice
- It gives flexibility, not license to write messy code
Rust’s design philosophy isn’t to restrict you—it’s to give you enough expressiveness within safety bounds. RefCell embodies this philosophy: rules aren’t meant to be broken, they’re meant to be understood and used.
Found this article helpful?
- Like: If this helped, give it a like to help others find it
- Share: Share with friends or colleagues learning Rust
- Follow: Follow Dream Beast Programming for more practical tech articles
- Comment: Have questions or thoughts? Join the discussion in comments
Your support is my biggest motivation to keep creating!
References: