For now, this reference is a best-effort document. We strive for validity and completeness, but are not yet there. In the future, the docs and lang teams will work together to figure out how best to do this. Until then, this is a best-effort attempt. If you find something wrong or missing, file an issue or send in a pull request.

Interior Mutability

Sometimes a type needs be mutated while having multiple aliases. In Rust this is achieved using a pattern called interior mutability. A type has interior mutability if its internal state can be changed through a shared reference to it. This goes against the usual requirement that the value pointed to by a shared reference is not mutated.

std::cell::UnsafeCell<T> type is the only allowed way in Rust 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. As with all other types, it is undefined behavior to have multiple &mut UnsafeCell<T> aliases.

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