Struct std::cell::UnsafeCell
1.0.0 · source · [−]#[repr(transparent)]#[repr(no_niche)]pub struct UnsafeCell<T> where
T: ?Sized, { /* private fields */ }
Expand description
The core primitive for interior mutability in Rust.
If you have a reference &T
, then normally in Rust the compiler performs optimizations based on
the knowledge that &T
points to immutable data. Mutating that data, for example through an
alias or by transmuting an &T
into an &mut T
, is considered undefined behavior.
UnsafeCell<T>
opts-out of the immutability guarantee for &T
: a shared reference
&UnsafeCell<T>
may point to data that is being mutated. This is called “interior mutability”.
All other types that allow internal mutability, such as Cell<T>
and RefCell<T>
, internally
use UnsafeCell
to wrap their data.
Note that only the immutability guarantee for shared references is affected by UnsafeCell
. The
uniqueness guarantee for mutable references is unaffected. There is no legal way to obtain
aliasing &mut
, not even with UnsafeCell<T>
.
The UnsafeCell
API itself is technically very simple: .get()
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 anUnsafeCell<T>
and cast it to an&T
, then the data inT
must remain immutable (modulo anyUnsafeCell
data found withinT
, 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 theUnsafeCell
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 whilst mutating the contents of an &UnsafeCell<T>
(even while other
&UnsafeCell<T>
references alias the cell) is
ok (provided you enforce the above invariants some other way), it is still undefined behavior
to have multiple &mut UnsafeCell<T>
aliases. That is, UnsafeCell
is a wrapper
designed to have a special interaction with shared accesses (i.e., through an
&UnsafeCell<_>
reference); there is no magic whatsoever when dealing with exclusive
accesses (e.g., through an &mut UnsafeCell<_>
): neither the cell nor the wrapped value
may be aliased for the duration of that &mut
borrow.
This is showcased by the .get_mut()
accessor, which is a safe getter that yields
a &mut T
.
Examples
Here is an example showcasing how to soundly mutate the contents of an UnsafeCell<_>
despite
there being multiple references aliasing the cell:
use std::cell::UnsafeCell;
let x: UnsafeCell<i32> = 42.into();
// Get multiple / concurrent / shared references to the same `x`.
let (p1, p2): (&UnsafeCell<i32>, &UnsafeCell<i32>) = (&x, &x);
unsafe {
// SAFETY: within this scope there are no other references to `x`'s contents,
// so ours is effectively unique.
let p1_exclusive: &mut i32 = &mut *p1.get(); // -- borrow --+
*p1_exclusive += 27; // |
} // <---------- cannot go beyond this point -------------------+
unsafe {
// SAFETY: within this scope nobody expects to have exclusive access to `x`'s contents,
// so we can have multiple shared accesses concurrently.
let p2_shared: &i32 = &*p2.get();
assert_eq!(*p2_shared, 42 + 27);
let p1_shared: &i32 = &*p1.get();
assert_eq!(*p1_shared, *p2_shared);
}
RunThe following example showcases the fact that exclusive access to an UnsafeCell<T>
implies exclusive access to its T
:
#![forbid(unsafe_code)] // with exclusive accesses,
// `UnsafeCell` is a transparent no-op wrapper,
// so no need for `unsafe` here.
use std::cell::UnsafeCell;
let mut x: UnsafeCell<i32> = 42.into();
// Get a compile-time-checked unique reference to `x`.
let p_unique: &mut UnsafeCell<i32> = &mut x;
// With an exclusive reference, we can mutate the contents for free.
*p_unique.get_mut() = 0;
// Or, equivalently:
x = UnsafeCell::new(0);
// When we own the value, we can extract the contents for free.
let contents: i32 = x.into_inner();
assert_eq!(contents, 0);
RunImplementations
sourceimpl<T> UnsafeCell<T>
impl<T> UnsafeCell<T>
const: 1.32.0 · sourcepub const fn new(value: T) -> UnsafeCell<T>
pub const fn new(value: T) -> UnsafeCell<T>
const: unstable · sourcepub fn into_inner(self) -> T
pub fn into_inner(self) -> T
sourceimpl<T> UnsafeCell<T> where
T: ?Sized,
impl<T> UnsafeCell<T> where
T: ?Sized,
const: 1.32.0 · sourcepub const fn get(&self) -> *mut T
pub const fn get(&self) -> *mut T
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
Examples
use std::cell::UnsafeCell;
let uc = UnsafeCell::new(5);
let five = uc.get();
Run1.56.0 (const: 1.56.0) · sourcepub const fn raw_get(this: *const UnsafeCell<T>) -> *mut T
pub const fn raw_get(this: *const UnsafeCell<T>) -> *mut T
Gets a mutable pointer to the wrapped value.
The difference from get
is that this function accepts a raw pointer,
which is useful to avoid the creation of temporary references.
The result 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
.
Examples
Gradual initialization of an UnsafeCell
requires raw_get
, as
calling get
would require creating a reference to uninitialized data:
use std::cell::UnsafeCell;
use std::mem::MaybeUninit;
let m = MaybeUninit::<UnsafeCell<i32>>::uninit();
unsafe { UnsafeCell::raw_get(m.as_ptr()).write(5); }
let uc = unsafe { m.assume_init() };
assert_eq!(uc.into_inner(), 5);
RunTrait Implementations
1.9.0 · sourceimpl<T> Debug for UnsafeCell<T> where
T: ?Sized,
impl<T> Debug for UnsafeCell<T> where
T: ?Sized,
1.10.0 · sourceimpl<T> Default for UnsafeCell<T> where
T: Default,
impl<T> Default for UnsafeCell<T> where
T: Default,
sourcefn default() -> UnsafeCell<T>
fn default() -> UnsafeCell<T>
Creates an UnsafeCell
, with the Default
value for T.
1.12.0 (const: unstable) · sourceimpl<T> From<T> for UnsafeCell<T>
impl<T> From<T> for UnsafeCell<T>
const: unstable · sourcefn from(t: T) -> UnsafeCell<T>
fn from(t: T) -> UnsafeCell<T>
Creates a new UnsafeCell<T>
containing the given value.
impl<T, U> CoerceUnsized<UnsafeCell<U>> for UnsafeCell<T> where
T: CoerceUnsized<U>,
impl<T> !RefUnwindSafe for UnsafeCell<T> where
T: ?Sized,
impl<T> !Sync for UnsafeCell<T> where
T: ?Sized,
Auto Trait Implementations
impl<T: ?Sized> Send for UnsafeCell<T> where
T: Send,
impl<T: ?Sized> Unpin for UnsafeCell<T> where
T: Unpin,
impl<T: ?Sized> UnwindSafe for UnsafeCell<T> where
T: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more