#[lang = "unsafe_cell"]
#[repr(transparent)]
pub struct UnsafeCell<T> where
T: ?Sized, { /* fields omitted */ }
The core primitive for interior mutability in Rust.
UnsafeCell<T>
is a type that wraps some T
and indicates unsafe interior operations on the
wrapped type. Types with an UnsafeCell<T>
field are considered to have an 'unsafe interior'.
The UnsafeCell<T>
type is the only legal way to obtain aliasable data that is considered
mutable. In general, transmuting an &T
type into an &mut T
is considered undefined behavior.
If you have a reference &SomeStruct
, then normally in Rust all fields of SomeStruct
are
immutable. The compiler makes optimizations based on the knowledge that &T
is not mutably
aliased or mutated, and that &mut T
is unique. UnsafeCell<T>
is the only core language
feature to work around this restriction. All other types that allow internal mutability, such as
Cell<T>
and RefCell<T>
, use UnsafeCell
to wrap their internal data.
The UnsafeCell
API itself is technically very simple: it gives you a raw pointer *mut T
to
its contents. It is up to you as the abstraction designer to use that raw pointer correctly.
The precise Rust aliasing rules are somewhat in flux, but the main points are not contentious:
-
If you create a safe reference with lifetime 'a
(either a &T
or &mut T
reference) that is accessible by safe code (for example, because you returned it),
then you must not access the data in any way that contradicts that reference for the
remainder of 'a
. For example, this means that if you take the *mut T
from an
UnsafeCell<T>
and cast it to an &T
, then the data in T
must remain immutable
(modulo any UnsafeCell
data found within T
, of course) until that reference's
lifetime expires. Similarly, if you create a &mut T
reference that is released to
safe code, then you must not access the data within the UnsafeCell
until that
reference expires.
-
At all times, you must avoid data races. If multiple threads have access to
the same UnsafeCell
, then any writes must have a proper happens-before relation to all other
accesses (or use atomics).
To assist with proper design, the following scenarios are explicitly declared legal
for single-threaded code:
-
A &T
reference can be released to safe code and there it can co-exist with other &T
references, but not with a &mut T
-
A &mut T
reference may be released to safe code provided neither other &mut T
nor &T
co-exist with it. A &mut T
must always be unique.
Note that while mutating or mutably aliasing the contents of an &UnsafeCell<T>
is
okay (provided you enforce the invariants some other way), it is still undefined behavior
to have multiple &mut UnsafeCell<T>
aliases.
use std::cell::UnsafeCell;
use std::marker::Sync;
struct NotThreadSafe<T> {
value: UnsafeCell<T>,
}
unsafe impl<T> Sync for NotThreadSafe<T> {}
Constructs a new instance of UnsafeCell
which will wrap the specified
value.
All access to the inner value through methods is unsafe
.
use std::cell::UnsafeCell;
let uc = UnsafeCell::new(5);
Unwraps the value.
use std::cell::UnsafeCell;
let uc = UnsafeCell::new(5);
let five = uc.into_inner();
Gets a mutable pointer to the wrapped value.
This can be cast to a pointer of any kind.
Ensure that the access is unique (no active references, mutable or not)
when casting to &mut T
, and ensure that there are no mutations
or mutable aliases going on when casting to &T
use std::cell::UnsafeCell;
let uc = UnsafeCell::new(5);
let five = uc.get();
Formats the value using the given formatter. Read more
Creates an UnsafeCell
, with the Default
value for T.
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
Immutably borrows from an owned value. Read more
🔬 This is a nightly-only experimental API. (get_type_id
)
this method will likely be replaced by an associated static
type Error = <U as TryFrom<T>>::Error
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
Mutably borrows from an owned value. Read more