Interior Mutability in Rust: Pattern Philosophy, Cell, and RefCell

Introduction

#

Usually, the borrow checker acts strictly: if a variable is declared without mut, the compiler will never allow modifying its fields through an immutable reference &T. This is standard Inherited Mutability.

However, in real-world code, situations arise where a component needs to store a cached response, record an error log, or update an internal identifier while holding only an immutable reference &self.

For these cases, the Rust standard library provides the Interior Mutability pattern. In this article, I explore how Cell and RefCell work, where they apply in practice, and how their runtime checks operate.

1. The Cell Container: Mutability Without References

#

The simplest tool for interior mutability is std::cell::Cell<T>.

The key property of Cell<T> is that it never hands out direct references &T or &mut T to the value inside it.

Instead of references, Cell operates by reading, writing, or moving values as a whole:

• get() — returns a copy of the inner value (requires T: Copy).
• set(val) — completely replaces the inner value with val.
• replace(val) — stores val inside the container and returns the previous value.
• take() — extracts the value, leaving Default::default() in its place.

use std::cell::Cell;

struct Counter {
    count: Cell<u32>,
}

fn main() {
    let c = Counter { count: Cell::new(0) };
    
    // The variable 'c' is NOT mutable! But we can freely modify count:
    c.count.set(c.count.get() + 1);
    
    println!("Current count: {}", c.count.get()); // Prints 1
}

2. The RefCell Container: Dynamic Borrow Checking

#

When storing a complex data structure (such as Vec<String>, HashMap, or a custom object) inside a container, copying it as a whole via Cell::get() is not an option.

For complex types, Rust provides std::cell::RefCell<T>.

RefCell<T> lets you request references to the inner value:

• .borrow() — returns a Ref<T> wrapper that acts like an immutable reference &T.
• .borrow_mut() — returns a RefMut<T> wrapper that acts like a mutable reference &mut T.
• .try_borrow() / .try_borrow_mut() — non-panicking variants returning Result, allowing safe checks when borrow conflicts might occur.

Runtime Borrow Checking

#

The standard Rust compiler enforces the rule “either multiple & or exactly one &mut” at compile time.

RefCell defers this borrow counter check to runtime.

use std::cell::RefCell;

fn main() {
    let data = RefCell::new(vec![1, 2, 3]);

    let mut b1 = data.borrow_mut();
    b1.push(4);

    // WARNING: b1 is still active! Attempting a second borrow_mut will PANIC:
    // let mut b2 = data.borrow_mut(); // ALREADY BORROWED PANIC!
}

Thanks to the RAII idiom, the Ref and RefMut smart pointers automatically decrement the borrow counter of RefCell in their Drop destructor when going out of scope. Therefore, calling drop(b1) explicitly allows the next data.borrow_mut() call to succeed smoothly.

3. Real-World Use Cases

#

Now that we understand how Cell and RefCell operate, let’s explore why changing data through an immutable reference &self is necessary when &mut self isn’t feasible.

In real-world code, using &mut self is not always an option. Here are three common scenarios:

1. Button Click Counters

#

Consider a standard UI button component. Let’s try updating a click counter inside a &self method:

 1// ?compile_fail
 2
 3struct Button {
 4    label: String,
 5    click_count: u32,
 6}
 7
 8impl Button {
 9    fn on_click(&self) {
10        println!("Button '{}' clicked!", self.label);
11        self.click_count += 1;
12    }
13}
14
15fn main() {
16    let btn = Button {
17        label: String::from("Submit"),
18        click_count: 0,
19    };
20    btn.on_click();
21}
22

 1use std::cell::Cell;
 2
 3struct Button {
 4    label: String,
 5    click_count: Cell<u32>,
 6}
 7
 8impl Button {
 9    fn on_click(&self) {
10        println!("Button '{}' clicked!", self.label);
11        let count = self.click_count.get();
12        self.click_count.set(count + 1);
13    }
14}
15
16fn main() {
17    let btn = Button {
18        label: String::from("Submit"),
19        click_count: Cell::new(0),
20    };
21
22    btn.on_click();
23    btn.on_click();
24    println!("Total button clicks: {}", btn.click_count.get());
25}
26

In UI frameworks, event handler methods usually accept &self because button instances are invoked from multiple parts of the application. Cell enables updating the internal click counter directly through &self without propagating &mut self across the entire call chain.

2. Log History Accumulation in Services

#

Another scenario involves a shared application context App, accessed across components via &App to read settings. With RefCell, any function can record warnings into a shared log vector on the fly:

struct App {
    name: String,
    // Log history stored inside the application struct
    logs: RefCell<Vec<String>>,
}

impl App {
    fn log_error(&self, msg: &str) {
        // Appends an entry to the vector holding only &self
        self.logs.borrow_mut().push(msg.to_string());
    }
}

3. State Flags (“Already Initialized”)

#

The same pattern applies to initialization flags in background audio players or loaders:

struct Player {
    is_playing: Cell<bool>,
}

impl Player {
    fn play(&self) {
        if !self.is_playing.get() {
            println!("Starting playback...");
            self.is_playing.set(true);
        }
    }
}

4. Multithreading Constraints

#

An essential caveat: Cell and RefCell containers are designed strictly for single-threaded execution.

Neither type implements the Sync marker trait, meaning the compiler prevents passing references to them across thread boundaries at build time.

A detailed walkthrough of multithreaded interior mutability (Mutex, RwLock) and the Send / Sync traits will be covered in a separate dedicated article.

Let’s explore how these types operate in practical interactive code slides:

 1use std::cell::Cell;
 2
 3struct Logger {
 4    log_count: Cell<usize>,
 5}
 6
 7impl Logger {
 8    fn new() -> Self {
 9        Logger {
10            log_count: Cell::new(0),
11        }
12    }
13
14    // Note: The method takes &self (immutable reference!), but mutates log_count!
15    fn log(&self, message: &str) {
16        println!("[LOG]: {message}");
17        let current = self.log_count.get();
18        self.log_count.set(current + 1);
19    }
20}
21
22fn main() {
23    let logger = Logger::new();
24
25    logger.log("First system log message");
26    logger.log("Second system log message");
27
28    println!("Total log entries: {}", logger.log_count.get());
29
30    // The replace method replaces the value and returns the old one
31    let old_val = logger.log_count.replace(100);
32    println!("Old count: {old_val}, new count: {}", logger.log_count.get());
33}
34

 1use std::cell::RefCell;
 2
 3struct UserCache {
 4    cache: RefCell<Vec<String>>,
 5}
 6
 7impl UserCache {
 8    fn new() -> Self {
 9        UserCache {
10            cache: RefCell::new(Vec::new()),
11        }
12    }
13
14    fn add_user(&self, name: String) {
15        // Request a mutable borrow at runtime
16        self.cache.borrow_mut().push(name);
17    }
18
19    fn print_users(&self) {
20        // Request an immutable borrow
21        let users = self.cache.borrow();
22        println!("Cached users: {:?}", *users);
23    }
24}
25
26fn main() {
27    let cache = UserCache::new();
28
29    cache.add_user("Alice".to_string());
30    cache.add_user("Bob".to_string());
31
32    cache.print_users();
33
34    // Check cache size
35    println!("Total users count: {}", cache.cache.borrow().len());
36}
37

Test Your Knowledge!

#

Take a short interactive quiz on interior mutability: