Struct yewtil::ptr::Mrc

pub struct Mrc<T> { /* fields omitted */ }

Mutable Reference Counted pointer

The Mrc has similar semantics to std::rc::Rc pointer, with notable differences that it does not support Weak pointers, it supports std::ops::DerefMut via the possibly allocating make_mut function, and that it can create immutable handles to its data (Irc).

This should make it just slightly more size efficient and performant than Rc, and should be more ergonomic to use than Rc given that you can mutably assign to it without much ceremony.

Passing Irc pointers to children guarantee that no intermediate component can modify the value behind the pointer. This makes it ideal for passing around configuration data where some components can ergonomicly "modify" and cheaply pass the pointers back to parent components, while other components can only read it.

Note

Assigning to an Mrc within Yew when you have passed shared copies of the ptr to child components, will always end up cloning the value stored in the Mrc. Rc makes this performance cost explicit, by making you use Rc::make_mut(). Because cloning is unavoidable in the context it was designed for, Mrc opts to provide nicer ergonomics around assignment.

Example

use yewtil::ptr::Mrc;

let mut mrc = Mrc::new(5);
*mrc = 10; // This just replaces the value because the mrc isn't shared.

assert_eq!(*mrc, 10);

let clone = mrc.clone();
*mrc = 20; // This operation clones the value and allocates space for it.

assert_eq!(*clone, 10);
assert_eq!(*mrc, 20);

Implementations

impl<T> Mrc<T>

pub fn new(value: T) -> Self

Allocates a value behind a Mrc pointer.

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

Attempts to get a mutable reference to the wrapped value.

If the pointer is not shared, it will return Some, whereas if multiple Mrcs or Ircs point to the value, this will return None.

Example

use yewtil::ptr::Mrc;
let mut mrc = Mrc::new(0);
assert!(mrc.get_mut().is_some());

let _clone = mrc.clone();
assert!(mrc.get_mut().is_none());

pub fn try_unwrap(self) -> Result<T, Self>

Tries to extract the value from the Mrc, returning the Mrc if there is one or more other pointers to the value.

Example

use yewtil::ptr::Mrc;
let mrc = Mrc::new(0);

let clone = mrc.clone();
let mrc = mrc.try_unwrap().expect_err("Should not be able to unwrap");

std::mem::drop(clone);
let value = mrc.try_unwrap().expect("Should get value");

pub fn get_count(&self) -> usize

Gets the reference count of the Mrc.

An exclusive Mrc will have a count of 1. The count is incremented on any cloning action and is decremented when drop is called.

Example

use yewtil::ptr::Mrc;
let mrc = Mrc::new(0);
assert_eq!(mrc.get_count(), 1);

let _clone = mrc.clone();
assert_eq!(mrc.get_count(), 2);

std::mem::drop(_clone);
assert_eq!(mrc.get_count(), 1);

pub fn is_exclusive(&self) -> bool

Returns true if no other pointers to the value exist.

use yewtil::ptr::Mrc;
let mrc = Mrc::new(0);
assert!(mrc.is_exclusive());

let _clone = mrc.clone();
assert!(!mrc.is_exclusive());

std::mem::drop(_clone);
assert!(mrc.is_exclusive());

pub fn irc(&self) -> Irc<T>

Returns an immutable reference counted pointer, pointing to the same value and reference count.

Example

use yewtil::ptr::{Mrc, Irc};
let mrc: Mrc<usize> =  Mrc::new(0);
let _irc: Irc<usize> = mrc.irc();

assert!(!mrc.is_exclusive());

pub fn into_irc(self) -> Irc<T>

Converts this Mrc into an Irc.

Example

use yewtil::ptr::{Mrc, Irc};
let mrc: Mrc<usize> =  Mrc::new(0);
let irc: Irc<usize> = mrc.into_irc();

assert!(irc.is_exclusive());

pub fn ptr_eq(lhs: &Self, rhs: &Self) -> bool

Checks pointers for equality.

Example

use yewtil::ptr::Mrc;
let mrc1 = Mrc::new(0);
let mrc2 = Mrc::new(0);
assert_eq!(mrc1, mrc2);
assert!(!Mrc::ptr_eq(&mrc1, &mrc2))

impl<T: Clone> Mrc<T>

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

Returns a mutable reference to the value if it has exclusive access. If it does not have exclusive access, it will make a clone of the data to acquire exclusive access.

Example

let mut mrc: Mrc<usize> = Mrc::new(0);

let _mut_ref: &mut usize = mrc.make_mut();
assert_eq!(mrc.get_count(), 1);

let clone = mrc.clone();
assert_eq!(mrc.get_count(), 2);

let _mut_ref: &mut usize = mrc.make_mut();
assert_eq!(mrc.get_count(), 1);
assert!(!Mrc::ptr_eq(&mrc, &clone))

pub fn unwrap_clone(self) -> T

Consumes the Mrc and returns the value from the Mrc if it is not shared or clones the value if another Mrc or Irc has access to it.

pub fn clone_inner(&self) -> T

Clones the value wrapped by the Mrc..

Trait Implementations

impl<T: Clone> AsMut<T> for Mrc<T>

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

Performs the conversion.

impl<T> AsRef<T> for Mrc<T>

fn as_ref(&self) -> &T

Performs the conversion.

impl<T> Borrow<T> for Mrc<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: Clone> BorrowMut<T> for Mrc<T>

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

Mutably borrows from an owned value.

impl<T> Clone for Mrc<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Mrc<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Mrc<T>

fn default() -> Self

Returns the "default value" for a type.

impl<T> Deref for Mrc<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: Clone> DerefMut for Mrc<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T> Drop for Mrc<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Eq> Eq for Mrc<T>

impl<T: Hash> Hash for Mrc<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<T: Ord> Ord for Mrc<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: PartialEq> PartialEq<Mrc<T>> for Mrc<T>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: PartialOrd> PartialOrd<Mrc<T>> for Mrc<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.