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

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

use symbolic_common::{AsSelf, SelfCell};

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

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

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

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

Implementations§

Creates a new SelfCell.

Safety

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

Example
use symbolic_common::SelfCell;

let owner = String::from("hello world");
let cell = SelfCell::new(owner, |s| unsafe { &*s });

Creates a new SelfCell which may fail to construct.

Safety

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

Example
use symbolic_common::SelfCell;

fn main() -> Result<(), std::str::Utf8Error> {
    let owner = Vec::from("hello world");
    let cell = SelfCell::try_new(owner, |s| unsafe { std::str::from_utf8(&*s) })?;
    Ok(())
}

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

Safety

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 and the borrowed reference has a stable address. This is useful, when cloning the owner by deriving a sub-object.

Example
use std::sync::Arc;
use symbolic_common::{AsSelf, SelfCell};

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

Returns a reference to the owner of this cell.

Example
use symbolic_common::SelfCell;

let owner = String::from("  hello  ");
let cell = SelfCell::new(owner, |s| unsafe { (*s).trim() });
assert_eq!(cell.owner(), "  hello  ");

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

Example
use symbolic_common::SelfCell;

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

Trait Implementations§

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.