[][src]Struct symbolic_common::SelfCell

pub struct SelfCell<O, D> where
    O: StableDeref
{ /* fields omitted */ }

A container carrying a derived object alongside its owner.

Warning: This is an inherently unsafe type that builds on top of StableDeref and AsSelf to establish somewhat safe memory semantics. Always try to avoid self-references by storing data in an outer scope or avoiding the need alltogether, first.

SelfCell stores an owner object that must implement StableDeref. This guarantees that the reference pointed to by the dependent object never moves over the lifetime of this object. This is already implemented for most heap-allocating types, like Box, Rc, Arc or ByteView.

Additionally, the dependent object must implement AsSelf. This guarantees that the borrow's lifetime and its lifetime bounds never exceed the lifetime of the owner. As such, an object Foo<'a> that borrows data from the owner, will be coerced down to Foo<'self> when borrowing. There are two constructor functions, new and try_new, each of which are passed a pointer to the owned data. Dereferencing this pointer is intentionally unsafe, and beware that a borrow of that pointer must not leave the callback.

While it is possible to store derived references in a SelfCell, too, there are simpler alternatives, such as owning_ref::OwningRef. Consider using such types before using SelfCell.

Example

struct Foo<'a>(&'a str);

impl<'slf> AsSelf<'slf> for Foo<'_> {
    type Ref = Foo<'slf>;

    fn as_self(&'slf self) -> &Self::Ref {
        self
    }
}

let cell = SelfCell::new(String::from("hello world"), |s| Foo(unsafe { &*s }));
assert_eq!(cell.get().0, "hello world");

StableDeref trait.StableDeref.html AsSelf trait.AsSelf.html

Methods

impl<'slf, O, T> SelfCell<O, T> where
    O: StableDeref + 'slf,
    T: AsSelf<'slf>, 
[src]

pub fn new<F>(owner: O, derive: F) -> Self where
    F: FnOnce(*const <O as Deref>::Target) -> T, 
[src]

Creates a new SelfCell.

The callback receives a pointer to the owned data. Note that a borrow to that data can only safely be used to derive the object and must not leave the callback.

pub fn try_new<E, F>(owner: O, derive: F) -> Result<Self, E> where
    F: FnOnce(*const <O as Deref>::Target) -> Result<T, E>, 
[src]

Creates a new SelfCell which may fail to construct.

The callback receives a pointer to the owned data. Note that a borrow to that data can only safely be used to derive the object and must not leave the callback.

pub unsafe fn from_raw(owner: O, derived: T) -> Self[src]

Unsafely creates a new SelfCell from a derived object by moving the owner.

This is an inherently unsafe process. The caller must guarantee that the derived object only borrows from the owner that is moved into this container. This is useful, when cloning the owner by deriving a sub-object.

struct Foo<'a>(&'a str);

impl<'slf> AsSelf<'slf> for Foo<'_> {
    type Ref = Foo<'slf>;

    fn as_self(&'slf self) -> &Self::Ref {
        self
    }
}

// Create a clonable owner and move it into cell
let owner = Arc::<str>::from("  hello  ");
let cell = SelfCell::new(owner, |s| Foo(unsafe { &*s }));

// Create a second derived object and clone the owner
let trimmed = Foo(cell.get().0.trim());
let cell2 = unsafe { SelfCell::from_raw(cell.owner().clone(), trimmed) };

// Now, drop the original cell and continue using the clone
assert_eq!(cell2.get().0, "hello");

pub fn owner(&self) -> &O[src]

Returns a reference to the owner of this cell.

pub fn get(&'slf self) -> &<T as AsSelf>::Ref[src]

Returns a safe reference to the derived object in this cell.

Trait Implementations

impl<O: Clone, D: Clone> Clone for SelfCell<O, D> where
    O: StableDeref
[src]

fn clone_from(&mut self, source: &Self)1.0.0[src]

Performs copy-assignment from source. Read more

impl<O: Debug, D: Debug> Debug for SelfCell<O, D> where
    O: StableDeref
[src]

Auto Trait Implementations

impl<O, D> Send for SelfCell<O, D> where
    D: Send,
    O: Send

impl<O, D> Sync for SelfCell<O, D> where
    D: Sync,
    O: Sync

Blanket Implementations

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

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

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.

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

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

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