W3cubDocs

/Rust

Struct std::cell::UnsafeCell

#[lang = "unsafe_cell"]
#[repr(transparent)]
#[repr(no_niche)]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 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: 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:

  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 while mutating or mutably aliasing the contents of an &UnsafeCell<T> is ok (provided you enforce the invariants some other way), it is still undefined behavior to have multiple &mut UnsafeCell<T> aliases.

Examples

use std::cell::UnsafeCell;

struct NotThreadSafe<T> {
    value: UnsafeCell<T>,
}

unsafe impl<T> Sync for NotThreadSafe<T> {}

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

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

impl<T> UnsafeCell<T> where
    T: ?Sized
[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();

pub fn raw_get(this: *const UnsafeCell<T>) -> *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);

Trait Implementations

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

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

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

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

Creates an UnsafeCell, with the Default value for T.

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

impl<T: ?Sized> !RefUnwindSafe for UnsafeCell<T>[src]1.9.0

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

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

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

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

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

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

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

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

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.

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.

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/cell/struct.UnsafeCell.html