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
sourceimpl<'slf, O, T> SelfCell<O, T> where
O: 'slf + StableDeref,
T: AsSelf<'slf>,
impl<'slf, O, T> SelfCell<O, T> where
O: 'slf + StableDeref,
T: AsSelf<'slf>,
sourcepub fn new<F>(owner: O, derive: F) -> SelfCell<O, T> where
F: FnOnce(*const <O as Deref>::Target) -> T,
pub fn new<F>(owner: O, derive: F) -> SelfCell<O, T> where
F: FnOnce(*const <O as Deref>::Target) -> T,
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 });
sourcepub fn try_new<E, F>(owner: O, derive: F) -> Result<SelfCell<O, T>, E> where
F: FnOnce(*const <O as Deref>::Target) -> Result<T, E>,
pub fn try_new<E, F>(owner: O, derive: F) -> Result<SelfCell<O, T>, E> where
F: FnOnce(*const <O as Deref>::Target) -> Result<T, E>,
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(())
}
sourcepub unsafe fn from_raw(owner: O, derived: T) -> SelfCell<O, T>
pub unsafe fn from_raw(owner: O, derived: T) -> SelfCell<O, T>
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");
Trait Implementations
Auto Trait Implementations
impl<O, D> RefUnwindSafe for SelfCell<O, D> where
D: RefUnwindSafe,
O: RefUnwindSafe,
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,
impl<O, D> Unpin for SelfCell<O, D> where
D: Unpin,
O: Unpin,
impl<O, D> UnwindSafe for SelfCell<O, D> where
D: UnwindSafe,
O: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<I, T> ExtractContext<I, ()> for T
impl<I, T> ExtractContext<I, ()> for T
fn extract_context(self, _original_input: I)
fn extract_context(self, _original_input: I)
Given the context attached to a nom error, and given the original input to the nom parser, extract more the useful context information. Read more
impl<T> FmtForward for T
impl<T> FmtForward for T
fn fmt_binary(self) -> FmtBinary<Self> where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self> where
Self: Binary,
Causes self
to use its Binary
implementation when Debug
-formatted. Read more
fn fmt_display(self) -> FmtDisplay<Self> where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self> where
Self: Display,
Causes self
to use its Display
implementation when
Debug
-formatted. Read more
fn fmt_lower_exp(self) -> FmtLowerExp<Self> where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self> where
Self: LowerExp,
Causes self
to use its LowerExp
implementation when
Debug
-formatted. Read more
fn fmt_lower_hex(self) -> FmtLowerHex<Self> where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self> where
Self: LowerHex,
Causes self
to use its LowerHex
implementation when
Debug
-formatted. Read more
fn fmt_octal(self) -> FmtOctal<Self> where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self> where
Self: Octal,
Causes self
to use its Octal
implementation when Debug
-formatted. Read more
fn fmt_pointer(self) -> FmtPointer<Self> where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self> where
Self: Pointer,
Causes self
to use its Pointer
implementation when
Debug
-formatted. Read more
fn fmt_upper_exp(self) -> FmtUpperExp<Self> where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self> where
Self: UpperExp,
Causes self
to use its UpperExp
implementation when
Debug
-formatted. Read more
fn fmt_upper_hex(self) -> FmtUpperHex<Self> where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self> where
Self: UpperHex,
Causes self
to use its UpperHex
implementation when
Debug
-formatted. Read more
fn fmt_list(self) -> FmtList<Self> where
&'a Self: for<'a> IntoIterator,
fn fmt_list(self) -> FmtList<Self> where
&'a Self: for<'a> IntoIterator,
Formats each item in a sequence. Read more
impl<T> Pipe for T where
T: ?Sized,
impl<T> Pipe for T where
T: ?Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
Pipes by value. This is generally the method you want to use. Read more
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R where
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R where
R: 'a,
Borrows self
and passes that borrow into the pipe function. Read more
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R where
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R where
R: 'a,
Mutably borrows self
and passes that borrow into the pipe function. Read more
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R where
Self: Borrow<B>,
B: 'a + ?Sized,
R: 'a,
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R where
Self: Borrow<B>,
B: 'a + ?Sized,
R: 'a,
Borrows self
, then passes self.borrow()
into the pipe function. Read more
fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R where
Self: BorrowMut<B>,
B: 'a + ?Sized,
R: 'a,
fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R where
Self: BorrowMut<B>,
B: 'a + ?Sized,
R: 'a,
Mutably borrows self
, then passes self.borrow_mut()
into the pipe
function. Read more
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R where
Self: AsRef<U>,
U: 'a + ?Sized,
R: 'a,
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R where
Self: AsRef<U>,
U: 'a + ?Sized,
R: 'a,
Borrows self
, then passes self.as_ref()
into the pipe function.
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R where
Self: AsMut<U>,
U: 'a + ?Sized,
R: 'a,
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R where
Self: AsMut<U>,
U: 'a + ?Sized,
R: 'a,
Mutably borrows self
, then passes self.as_mut()
into the pipe
function. Read more
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R where
Self: Deref<Target = T>,
T: 'a + ?Sized,
R: 'a,
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R where
Self: Deref<Target = T>,
T: 'a + ?Sized,
R: 'a,
Borrows self
, then passes self.deref()
into the pipe function.
impl<I> RecreateContext<I> for I
impl<I> RecreateContext<I> for I
fn recreate_context(_original_input: I, tail: I) -> I
fn recreate_context(_original_input: I, tail: I) -> I
Given the original input, as well as the context reported by nom, recreate a context in the original string where the error occurred. Read more
impl<T> Tap for T
impl<T> Tap for T
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self where
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self where
Self: Borrow<B>,
B: ?Sized,
Immutable access to the Borrow<B>
of a value. Read more
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self where
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self where
Self: BorrowMut<B>,
B: ?Sized,
Mutable access to the BorrowMut<B>
of a value. Read more
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self where
Self: AsRef<R>,
R: ?Sized,
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self where
Self: AsRef<R>,
R: ?Sized,
Immutable access to the AsRef<R>
view of a value. Read more
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self where
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self where
Self: AsMut<R>,
R: ?Sized,
Mutable access to the AsMut<R>
view of a value. Read more
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self where
Self: Deref<Target = T>,
T: ?Sized,
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self where
Self: Deref<Target = T>,
T: ?Sized,
Immutable access to the Deref::Target
of a value. Read more
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self where
Self: DerefMut<Target = T> + Deref,
T: ?Sized,
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self where
Self: DerefMut<Target = T> + Deref,
T: ?Sized,
Mutable access to the Deref::Target
of a value. Read more
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
Calls .tap()
only in debug builds, and is erased in release builds.
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
Calls .tap_mut()
only in debug builds, and is erased in release
builds. Read more
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self where
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self where
Self: Borrow<B>,
B: ?Sized,
Calls .tap_borrow()
only in debug builds, and is erased in release
builds. Read more
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self where
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self where
Self: BorrowMut<B>,
B: ?Sized,
Calls .tap_borrow_mut()
only in debug builds, and is erased in release
builds. Read more
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self where
Self: AsRef<R>,
R: ?Sized,
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self where
Self: AsRef<R>,
R: ?Sized,
Calls .tap_ref()
only in debug builds, and is erased in release
builds. Read more
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self where
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self where
Self: AsMut<R>,
R: ?Sized,
Calls .tap_ref_mut()
only in debug builds, and is erased in release
builds. Read more