Interior mutability - The Rust Reference

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

[interior-mut]

# Interior mutability

[interior-mut.intro]

Sometimes a type needs to be mutated while having multiple aliases. In Rust this is achieved using a pattern called interior mutability.

[interior-mut.shared-ref]

A type has interior mutability if its internal state can be changed through a shared reference to it.

[interior-mut.no-constraint]

This goes against the usual requirement that the value pointed to by a shared reference is not mutated.

[interior-mut.unsafe-cell]

`std::cell::UnsafeCell<T>` type is the only allowed way to disable this requirement. When `UnsafeCell<T>` is immutably aliased, it is still safe to mutate, or obtain a mutable reference to, the `T` it contains.

[interior-mut.mut-unsafe-cell]

As with all other types, it is undefined behavior to have multiple `&mut UnsafeCell<T>` aliases.

[interior-mut.abstraction]

Other types with interior mutability can be created by using `UnsafeCell<T>` as a field. The standard library provides a variety of types that provide safe interior mutability APIs.

[interior-mut.ref-cell]

For example, `std::cell::RefCell<T>` uses run-time borrow checks to ensure the usual rules around multiple references.

[interior-mut.atomic]

The `std::sync::atomic` module contains types that wrap a value that is only accessed with atomic operations, allowing the value to be shared and mutated across threads.