Struct qcell::LCellOwner

pub struct LCellOwner<'id> { /* private fields */ }

Borrowing-owner of zero or more LCell instances.

Use LCellOwner::scope(|owner| ...) to create an instance of this type. The key piece of Rust syntax that enables this is for<'id>. This allows creating an invariant lifetime within a closure, which is different to any other Rust lifetime thanks to the techniques explained in various places: section 6.3 of this thesis from Gankro, this Reddit post, and this Rust playground example. Also see this Reddit comment and its linked playground code.

Alternatively, if the generativity feature is enabled, the generativity crate can be used to create an owner as follows: make_guard!(guard); let mut owner = LCellOwner::new(guard);. However note that the Rust compiler error messages may be more confusing with generativity if you make a mistake and use the wrong owner for a cell.

Some history: GhostCell by pythonesque predates the creation of LCell, and inspired it. Discussion of GhostCell on Reddit showed that a lifetime-based approach to cells was feasible, but unfortunately the ghost_cell.rs source didn’t seem to be available under a community-friendly licence. So I went back to first principles and created LCell from TCell code, combined with invariant lifetime code derived from the various community sources that predate GhostCell. Later Send and Sync support for LCell was contributed independently.

See also crate documentation.

Implementations

impl<'id> LCellOwner<'id>

pub fn scope<F>(f: F) where
    F: for<'scope_id> FnOnce(LCellOwner<'scope_id>), 

Create a new LCellOwner, with a new lifetime, that exists only within the scope of the execution of the given closure call. If two scope calls are nested, then the two owners get different lifetimes.

use qcell::{LCellOwner, LCell};
LCellOwner::scope(|owner| {
    let cell = LCell::new(100);
    assert_eq!(cell.ro(&owner), &100);
})

pub fn new(_guard: Guard<'id>) -> Self

Available on crate feature generativity only.

Create a new LCellOwner with a unique lifetime from a Guard.

use qcell::{generativity::make_guard, LCellOwner, LCell};
make_guard!(guard);
let mut owner = LCellOwner::new(guard);
let cell = LCell::new(100);
assert_eq!(cell.ro(&owner), &100);

pub fn cell<T>(&self, value: T) -> LCell<'id, T>

Create a new cell owned by this owner instance. See also LCell::new.

pub fn ro<'a, T: ?Sized>(&'a self, lc: &'a LCell<'id, T>) -> &'a T

Borrow contents of a LCell immutably (read-only). Many LCell instances can be borrowed immutably at the same time from the same owner.

pub fn rw<'a, T: ?Sized>(&'a mut self, lc: &'a LCell<'id, T>) -> &'a mut T

Borrow contents of a LCell mutably (read-write). Only one LCell at a time can be borrowed from the owner using this call. The returned reference must go out of scope before another can be borrowed.

pub fn rw2<'a, T: ?Sized, U: ?Sized>(
    &'a mut self,
    lc1: &'a LCell<'id, T>,
    lc2: &'a LCell<'id, U>
) -> (&'a mut T, &'a mut U)

Borrow contents of two LCell instances mutably. Panics if the two LCell instances point to the same memory.

pub fn rw3<'a, T: ?Sized, U: ?Sized, V: ?Sized>(
    &'a mut self,
    lc1: &'a LCell<'id, T>,
    lc2: &'a LCell<'id, U>,
    lc3: &'a LCell<'id, V>
) -> (&'a mut T, &'a mut U, &'a mut V)

Borrow contents of three LCell instances mutably. Panics if any pair of LCell instances point to the same memory.