Struct Res

pub struct Res<T: ?Sized + 'static> { /* private fields */ }

Associated reference-counted handle to data.

This item can only mutably accessed using via.

Res stands for resource.

use mutcy::{Assoc, Res};

let mut assoc = Assoc::new();
let item = Res::new_in(41, &assoc);

let value: i32 = assoc.enter(|x| {
    let mut data = item.via(x);
    *data += 1;
    *data
});

assert_eq!(value, 42);

Implementations

impl<T: 'static> Res<T>

pub fn new_in<A: Associated>(value: T, assoc: &A) -> Self

Create a new Res with the same association as A.

pub fn new_cyclic_in<F, A>(data_fn: F, assoc: &A) -> Self

where F: FnOnce(&WeakRes<T>) -> T, A: Associated,

Create a new cyclic Res with the same association as A.

data_fn is given a reference to a WeakRes.

See also Rc::new_cyclic.

use mutcy::{Assoc, Res, WeakRes};

let mut assoc = Assoc::new();

struct MyItem(i32, WeakRes<Self>);
let item = Res::new_cyclic_in(|weak| MyItem(41, weak.clone()), &assoc);

assoc.enter(|x| {
    let mut data = item.via(x);
    data.0 += 1;

    let data_reborrow = data.1.upgrade().unwrap().mutate().via(x);
    assert_eq!(data_reborrow.0, 42);
});

impl<T: ?Sized + 'static> Res<T>

pub fn mutate(&self) -> Self

Creates a new handle for mutation chaining

Equivalent to Clone::clone but provides clearer semantics when establishing new mutation chains through via.

Why use this instead of clone()?

Avoids double-borrow scenarios in method chains:

impl MyType {
    fn method(self: &mut Mut<Self>) {
        // ERROR: Cannot borrow `self` mutably more than once
        // self.inner.via(self);

        // OK
        let inner = self.inner.mutate().via(self);
    }
}

Correct usage with cloning:

impl MyType {
    fn method(self: &mut Mut<Self>) {
        // Clone first to avoid overlapping borrows
        self.inner.mutate().via(self);
    }
}

pub fn via<'a: 'b, 'b, A: 'static>( self, source: &'a mut Mut<'_, A>, ) -> Mut<'b, T>

Relinquish a previous Mut and creates a Mut of self.

Since references to T a Mut<T> require Deref or DerefMut, calling this function will relinquish all such borrows on Mut<T>. This makes it safe to acquire a mutable reference recursively.

In effect, there exists only a single accessible Mut<T> for any Res<T> in a single association. This function checks if the association matches to prevent multiple Mut<T> being accessible for a Res<T> in the same Assoc. Assoc::enter borrows the association mutably, thus guaranteeing that only one Mut<T> can be live per association.

Panics

Will panic if the arguments’ associated Assocs differ.

struct MyType {
    this: Res<Self>,
    value: i32,
}

impl MyType {
    fn method(self: &mut Mut<Self>) {
        let value_reference: &mut i32 = &mut self.value;

        // `via` relinquishes `value_reference`, because it has a dependency on
        // `self` that conflicts with `via`.
        self.this.mutate().via(self);

        // ERROR: We cannot now use `value_reference`.
        // *value_reference += 1;

        // We need to reborrow instead.
        let value_reference: &mut i32 = &mut self.value;
    }
}

pub fn downgrade(this: &Res<T>) -> WeakRes<T>

Create a weakly referencing to this Res.

See Rc::downgrade.

Trait Implementations

impl<T: ?Sized + 'static> Clone for Res<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: 'static> Associated for Res<T>

impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Res<U>> for Res<T>