core::cell::UnsafeCell - Rust
Description: API documentation for the Rust `UnsafeCell` struct in crate `core`.
Keywords: rust, rustlang, rust-lang, UnsafeCell

# 1.0.0[−][src]Struct core::cell::UnsafeCell

    #[lang = "unsafe_cell"]
    #[repr(transparent)]
    #[repr(no_niche)]pub struct UnsafeCell<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 the restriction that `&T` may not be mutated. All other types that allow internal mutability, such as `Cell<T>` and `RefCell<T>`, use `UnsafeCell` to wrap their internal data. 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 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:

1. 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`

2. 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 non-`unsafe` 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);
    }

Run

The following example showcases the fact that exclusive access to an `UnsafeCell<T>` implies exclusive access to its `T`:

    #![feature(unsafe_cell_get_mut)]
    #![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);

Run

## Implementations

### `impl<T> UnsafeCell<T>`[src]

#### `pub const fn new(value: T) -> UnsafeCell<T>`[src]

Constructs a new instance of `UnsafeCell` which will wrap the specified value.

All access to the inner value through methods is `unsafe`.

# Examples

    use std::cell::UnsafeCell;

    let uc = UnsafeCell::new(5);

Run

#### `pub fn into_inner(self) -> T`[src]

Unwraps the value.

# Examples

    use std::cell::UnsafeCell;

    let uc = UnsafeCell::new(5);

    let five = uc.into_inner();

Run

### `impl<T: ?Sized> UnsafeCell<T>`[src]

#### `pub const fn get(&self) -> *mut T`[src]

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();

Run

#### `pub fn get_mut(&mut self) -> &mut T`[src]

🔬 This is a nightly-only experimental API. (`unsafe_cell_get_mut` #76943)

Returns a mutable reference to the underlying data.

This call borrows the `UnsafeCell` mutably (at compile-time) which guarantees that we possess the only reference.

# Examples

    #![feature(unsafe_cell_get_mut)]
    use std::cell::UnsafeCell;

    let mut c = UnsafeCell::new(5);
    *c.get_mut() += 1;

    assert_eq!(*c.get_mut(), 6);

Run

#### `pub const fn raw_get(this: *const Self) -> *mut T`[src]

🔬 This is a nightly-only experimental API. (`unsafe_cell_raw_get` #66358)

Gets a mutable pointer to the wrapped value. The difference to `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:

    #![feature(unsafe_cell_raw_get)]
    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);

Run

## Trait Implementations

### `impl<T: CoerceUnsized<U>, U> CoerceUnsized<UnsafeCell<U>> for UnsafeCell<T>`[src]

### `impl<T: ?Sized + Debug> Debug for UnsafeCell<T>`1.9.0[src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result`[src]

Formats the value using the given formatter. Read more

### `impl<T: Default> Default for UnsafeCell<T>`1.10.0[src]

#### `fn default() -> UnsafeCell<T>`[src]

Creates an `UnsafeCell`, with the `Default` value for T.

### `impl<T> From<T> for UnsafeCell<T>`1.12.0[src]

#### `fn from(t: T) -> UnsafeCell<T>`[src]

Performs the conversion.

### `impl<T: ?Sized> !Sync for UnsafeCell<T>`[src]

## Auto Trait Implementations

### `impl<T: ?Sized> Send for UnsafeCell<T> where
T: Send,`

### `impl<T: ?Sized> Unpin for UnsafeCell<T> where
T: Unpin,`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&Self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&Self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut Self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> From<!> for T`[src]

#### `pub fn from(!) -> T`[src]

Performs the conversion.

### `impl<T> From<T> for T`[src]

#### `pub fn from(T) -> T`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(Self) -> U`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(Self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.