Struct ghost_cell::ghost_cell::GhostCell

pub struct GhostCell<'brand, T: ?Sized> { /* private fields */ }

Branded wrapper for a value, whose type is T.

A GhostCell<'x, T> owns an instance of type T:

• Unique access to the cell allows unimpeded access to the contained value.
• Shared access to the cell requires mediating access through the associated GhostToken<'x, T> which will enforce at compile-time the aliasing XOR mutability safety property.

Implementations

impl<'brand, T> GhostCell<'brand, T>

pub const fn new(value: T) -> Self

Wraps some T into a GhostCell with brand 'brand which associates it to one, and only one, GhostToken.

Example

use ghost_cell::{GhostToken, GhostCell};

GhostToken::new(|token| {
    let cell = GhostCell::new(42);

    assert_eq!(42, *cell.borrow(&token));
});

pub fn into_inner(self) -> T

Turns an owned GhostCell back into owned data.

Example

use ghost_cell::{GhostToken, GhostCell};

let value = GhostToken::new(|mut token| {
    let cell = GhostCell::new(42);

    cell.into_inner()
});

assert_eq!(42, value);

impl<'brand, T: ?Sized> GhostCell<'brand, T>

pub fn borrow<'a>(&'a self, _: &'a GhostToken<'brand>) -> &'a T

Immutably borrows the GhostCell with the same-branded token.

Example

use ghost_cell::{GhostToken, GhostCell};

let n = 12;

let value = GhostToken::new(|mut token| {
    let cell = GhostCell::new(42);

    let vec: Vec<_> = (0..n).map(|_| &cell).collect();

    let one: &i32 = vec[1].borrow(&token);
    let two: &i32 = vec[2].borrow(&token);

    *one + *two
});

assert_eq!(84, value);

pub fn borrow_mut<'a>(&'a self, _: &'a mut GhostToken<'brand>) -> &'a mut T

Mutably borrows the GhostCell with the same-branded token.

Example

use ghost_cell::{GhostToken, GhostCell};

let n = 12;

let value = GhostToken::new(|mut token| {
    let cell = GhostCell::new(42);

    let vec: Vec<_> = (0..n).map(|_| &cell).collect();

    let reference: &mut i32 = vec[n / 2].borrow_mut(&mut token);
    *reference = 33;

    *cell.borrow(&token)
});

assert_eq!(33, value);

pub const fn as_ptr(&self) -> *mut T

Returns a raw pointer to the contained value.

pub fn get_mut(&mut self) -> &mut T

Turns a mutably borrowed GhostCell into mutably borrowed data.

self is mutably borrowed for the lifetime of the result, ensuring the absence of aliasing.

Example

use ghost_cell::{GhostToken, GhostCell};

let value = GhostToken::new(|mut token| {
    let mut cell = GhostCell::new(42);

    *cell.get_mut() = 33;

    *cell.borrow(&token)
});

assert_eq!(33, value);

pub fn from_mut(t: &mut T) -> &mut Self

Turns mutably borrowed data into a mutably borrowed GhostCell.

t is mutably borrowed for the lifetime of the result, ensuring the absence of aliasing.

Example

use ghost_cell::{GhostToken, GhostCell};

let n = 12;
let mut value = 42;

GhostToken::new(|mut token| {
    let cell = GhostCell::from_mut(&mut value);

    let vec: Vec<_> = (0..n).map(|_| &cell).collect();

    *vec[n / 2].borrow_mut(&mut token) = 33;
});

assert_eq!(33, value);

impl<'brand, T> GhostCell<'brand, T>

pub fn replace(&self, value: T, token: &mut GhostToken<'brand>) -> T

Returns the value, replacing it by the supplied one.

Example

use ghost_cell::{GhostToken, GhostCell};

let n = 12;

let value = GhostToken::new(|mut token| {
    let cell = GhostCell::new(42);

    let vec: Vec<_> = (0..n).map(|_| &cell).collect();

    let previous = vec[n / 2].replace(33, &mut token);
    assert_eq!(42, previous);

    *cell.borrow(&token)
});

assert_eq!(33, value);

pub fn take(&self, token: &mut GhostToken<'brand>) -> T

where T: Default,

Returns the value, replacing it with the default value.

Example

use ghost_cell::{GhostToken, GhostCell};

let n = 12;

let value = GhostToken::new(|mut token| {
    let cell = GhostCell::new(42);

    let vec: Vec<_> = (0..n).map(|_| &cell).collect();

    let previous = vec[n / 2].take(&mut token);
    assert_eq!(42, previous);

    *cell.borrow(&token)
});

assert_eq!(0, value);

impl<'brand, T> GhostCell<'brand, [T]>

pub fn as_slice_of_cells(&self) -> &[GhostCell<'brand, T>]

Returns a slice of cells from a cell containing a slice.

Example

use ghost_cell::{GhostToken, GhostCell};

let n = 12;

let value = GhostToken::new(|mut token| {
    let mut vec: Vec<_> = (0..n).collect();
    let cell = GhostCell::from_mut(&mut vec[..]);

    let slice = cell.as_slice_of_cells();

    *slice[n / 2].borrow_mut(&mut token) = 33;

    vec[n / 2]
});

assert_eq!(33, value);

pub fn from_slice_of_cells<'slice>( slice: &'slice [GhostCell<'brand, T>] ) -> &'slice Self

Returns a cell containing a slice from slice of cells.

Example

use ghost_cell::{GhostToken, GhostCell};

let n = 12;

let value = GhostToken::new(|mut token| {
    let mut vec: Vec<_> = (0..n).collect();
    let cell = GhostCell::from_mut(&mut vec[..]);
    let all_elements = cell.as_slice_of_cells();

    let quad = GhostCell::from_slice_of_cells(&all_elements[4..][..4]);
    quad.borrow_mut(&mut token).copy_from_slice(&33u32.to_be_bytes());

    vec.iter().position(|&v| v == 33)
});

assert_eq!(Some(7), value);

impl<'brand, T, const N: usize> GhostCell<'brand, [T; N]>

pub fn as_array_of_cells(&self) -> &[GhostCell<'brand, T>; N]

Returns a reference to an array of cells from a cell containing an array.

Example

use ghost_cell::{GhostToken, GhostCell};

let value = GhostToken::new(|mut token| {
    let mut array = [0, 1, 2, 3, 5];
    let n = array.len();

    let cell = GhostCell::from_mut(&mut array);

    let inner = cell.as_array_of_cells();

    *inner[n / 2].borrow_mut(&mut token) = 33;

    array[n / 2]
});

assert_eq!(33, value);

pub fn from_array_of_cells<'a>(array: &'a [GhostCell<'brand, T>; N]) -> &'a Self

Returns a cell containing an array from an array of cells.

Example

use ghost_cell::{GhostToken, GhostCell};

let value = GhostToken::new(|mut token| {
    let mut array = [0, 1, 2, 3, 5];
    let n = array.len();

    let cell = GhostCell::from_mut(&mut array);

    let inner = cell.as_array_of_cells();

    let inner = GhostCell::from_array_of_cells(&inner);

    inner.borrow_mut(&mut token)[n / 2] = 33;

    array[n / 2]
});

assert_eq!(33, value);

impl<'brand> GhostCell<'brand, ()>

pub fn as_tuple_of_cells(&self) -> &()

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>(tuple: &'a ()) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0> GhostCell<'brand, (T0,)>

pub fn as_tuple_of_cells(&self) -> &(GhostCell<'brand, T0>,)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>(tuple: &'a (GhostCell<'brand, T0>,)) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1> GhostCell<'brand, (T0, T1)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2> GhostCell<'brand, (T0, T1, T2)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3> GhostCell<'brand, (T0, T1, T2, T3)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3, T4> GhostCell<'brand, (T0, T1, T2, T3, T4)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3, T4, T5> GhostCell<'brand, (T0, T1, T2, T3, T4, T5)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3, T4, T5, T6> GhostCell<'brand, (T0, T1, T2, T3, T4, T5, T6)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3, T4, T5, T6, T7> GhostCell<'brand, (T0, T1, T2, T3, T4, T5, T6, T7)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3, T4, T5, T6, T7, T8> GhostCell<'brand, (T0, T1, T2, T3, T4, T5, T6, T7, T8)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>, GhostCell<'brand, T8>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>, GhostCell<'brand, T8>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3, T4, T5, T6, T7, T8, T9> GhostCell<'brand, (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>, GhostCell<'brand, T8>, GhostCell<'brand, T9>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>, GhostCell<'brand, T8>, GhostCell<'brand, T9>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10> GhostCell<'brand, (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>, GhostCell<'brand, T8>, GhostCell<'brand, T9>, GhostCell<'brand, T10>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>, GhostCell<'brand, T8>, GhostCell<'brand, T9>, GhostCell<'brand, T10>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

impl<'brand, T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11> GhostCell<'brand, (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11)>

pub fn as_tuple_of_cells( &self ) -> &(GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>, GhostCell<'brand, T8>, GhostCell<'brand, T9>, GhostCell<'brand, T10>, GhostCell<'brand, T11>)

Returns a reference to a tuple of cells from a cell containing a tuple.

pub fn from_tuple_of_cells<'a>( tuple: &'a (GhostCell<'brand, T0>, GhostCell<'brand, T1>, GhostCell<'brand, T2>, GhostCell<'brand, T3>, GhostCell<'brand, T4>, GhostCell<'brand, T5>, GhostCell<'brand, T6>, GhostCell<'brand, T7>, GhostCell<'brand, T8>, GhostCell<'brand, T9>, GhostCell<'brand, T10>, GhostCell<'brand, T11>) ) -> &'a Self

Returns a cell containing a tuple from a tuple of cells.

Trait Implementations

impl<'brand, T: ?Sized> AsMut<T> for GhostCell<'brand, T>

fn as_mut(&mut self) -> &mut T

Converts this type into a mutable reference of the (usually inferred) input type.

impl<'brand, T: Default> Default for GhostCell<'brand, T>

fn default() -> Self

Returns the “default value” for a type.

impl<'brand, T> From<T> for GhostCell<'brand, T>

fn from(t: T) -> Self

Converts to this type from the input type.

impl<'brand, T: ?Sized + Send> Send for GhostCell<'brand, T>

A GhostCell<'_, T> owns a T, so it cannot be sent across threads if T cannot.

Conversely, a GhostCell does not add any state on top of T, so if T can be sent across threads, so can GhostCell<'_, T>

impl<'brand, T: ?Sized + Send + Sync> Sync for GhostCell<'brand, T>

A GhostCell<'_, T> owns a T, so it cannot be accessed from different threads if T cannot.

Conversely, a GhostCell does not add any state on top of T, so if T can be accessed from different threads, so can GhostCell<'_, T>. T also needs to be sendable across threads, because a T can be extracted from a &GhostCell<'brand, T> via GhostCell::replace.