Struct RefCellRefMutStack 

pub struct RefCellRefMutStack<'root, T: ?Sized> { /* private fields */ }

Implementations

impl<'root, T: ?Sized> RefCellRefMutStack<'root, T>

pub fn new(root: &'root RefCell<T>) -> Result<Self, BorrowMutError>

Create a new MutRefStack from a mutable reference to the root of a recursive data structure.

Examples found in repository

examples/cyclic.rs (line 43)

fn main() {
    let cycle_a = Rc::new(RefCell::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let cycle_b = Rc::new(RefCell::new(CyclicDataStructure {
        data: 1_u32,
        next: None,
    }));
    let cycle_c = Rc::new(RefCell::new(CyclicDataStructure {
        data: 2_u32,
        next: None,
    }));

    cycle_a.borrow_mut().insert_next(cycle_b.clone());
    cycle_b.borrow_mut().insert_next(cycle_c.clone());
    cycle_c.borrow_mut().insert_next(cycle_a.clone());

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = RefCellRefMutStack::new(&cycle_a).expect("not mutable borrowed yet");
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let Err(_borrow_error) = stack
            .descend_with(CyclicDataStructure::next)
            .expect("no node has no next")
        {
            println!("Found a cycle!");
            break;
        }
        println!("Descended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let None = stack.ascend() {
            println!("Reached the head of the linked list!");
            break;
        }
        println!("Ascended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }

    println!("(Breaking the cycle to prevent miri from complaining about memory leaks)");
    stack.top_mut().take_next();
}

pub fn raw_top_mut(&mut self) -> *mut T

pub fn top(&self) -> &T

Obtain a shared reference to the top of the stack.

Examples found in repository

examples/cyclic.rs (line 44)

fn main() {
    let cycle_a = Rc::new(RefCell::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let cycle_b = Rc::new(RefCell::new(CyclicDataStructure {
        data: 1_u32,
        next: None,
    }));
    let cycle_c = Rc::new(RefCell::new(CyclicDataStructure {
        data: 2_u32,
        next: None,
    }));

    cycle_a.borrow_mut().insert_next(cycle_b.clone());
    cycle_b.borrow_mut().insert_next(cycle_c.clone());
    cycle_c.borrow_mut().insert_next(cycle_a.clone());

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = RefCellRefMutStack::new(&cycle_a).expect("not mutable borrowed yet");
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let Err(_borrow_error) = stack
            .descend_with(CyclicDataStructure::next)
            .expect("no node has no next")
        {
            println!("Found a cycle!");
            break;
        }
        println!("Descended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let None = stack.ascend() {
            println!("Reached the head of the linked list!");
            break;
        }
        println!("Ascended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }

    println!("(Breaking the cycle to prevent miri from complaining about memory leaks)");
    stack.top_mut().take_next();
}

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

Obtain a mutable reference to the top of the stack.

Examples found in repository

examples/cyclic.rs (line 67)

fn main() {
    let cycle_a = Rc::new(RefCell::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let cycle_b = Rc::new(RefCell::new(CyclicDataStructure {
        data: 1_u32,
        next: None,
    }));
    let cycle_c = Rc::new(RefCell::new(CyclicDataStructure {
        data: 2_u32,
        next: None,
    }));

    cycle_a.borrow_mut().insert_next(cycle_b.clone());
    cycle_b.borrow_mut().insert_next(cycle_c.clone());
    cycle_c.borrow_mut().insert_next(cycle_a.clone());

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = RefCellRefMutStack::new(&cycle_a).expect("not mutable borrowed yet");
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let Err(_borrow_error) = stack
            .descend_with(CyclicDataStructure::next)
            .expect("no node has no next")
        {
            println!("Found a cycle!");
            break;
        }
        println!("Descended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let None = stack.ascend() {
            println!("Reached the head of the linked list!");
            break;
        }
        println!("Ascended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }

    println!("(Breaking the cycle to prevent miri from complaining about memory leaks)");
    stack.top_mut().take_next();
}

pub fn is_at_root(&self) -> bool

Is this MutRefStack currently at its root?

pub fn inject_top( &mut self, new_top: &'root RefCell<T>, ) -> Result<&mut T, BorrowMutError>

Inject a new reference to the top of the stack. The reference still must live as long as the root of the stack.

pub fn inject_with( &mut self, f: impl FnOnce(&mut T) -> Option<&'root RefCell<T>>, ) -> Option<Result<&mut T, BorrowMutError>>

Inject a new reference to the top of the stack. The reference still must live as long as the root of the stack.

pub fn descend_with( &mut self, f: impl for<'node> FnOnce(&'node mut T) -> Option<&'node RefCell<T>>, ) -> Option<Result<&mut T, BorrowMutError>>

Descend into the recursive data structure, returning a mutable reference to the new top element. Rust’s borrow checker enforces that the closure cannot inject any lifetime (other than 'static), because the closure must work for any lifetime 'node.

Examples found in repository

examples/cyclic.rs (line 47)

fn main() {
    let cycle_a = Rc::new(RefCell::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let cycle_b = Rc::new(RefCell::new(CyclicDataStructure {
        data: 1_u32,
        next: None,
    }));
    let cycle_c = Rc::new(RefCell::new(CyclicDataStructure {
        data: 2_u32,
        next: None,
    }));

    cycle_a.borrow_mut().insert_next(cycle_b.clone());
    cycle_b.borrow_mut().insert_next(cycle_c.clone());
    cycle_c.borrow_mut().insert_next(cycle_a.clone());

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = RefCellRefMutStack::new(&cycle_a).expect("not mutable borrowed yet");
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let Err(_borrow_error) = stack
            .descend_with(CyclicDataStructure::next)
            .expect("no node has no next")
        {
            println!("Found a cycle!");
            break;
        }
        println!("Descended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let None = stack.ascend() {
            println!("Reached the head of the linked list!");
            break;
        }
        println!("Ascended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }

    println!("(Breaking the cycle to prevent miri from complaining about memory leaks)");
    stack.top_mut().take_next();
}

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

Ascend back up from the recursive data structure, returning a mutable reference to the new top element, if it changed. If we are not currently at the root, ascend and return a reference to the new top. If we are already at the root, returns None (the top is the root and does not change).

Examples found in repository

examples/cyclic.rs (line 58)

fn main() {
    let cycle_a = Rc::new(RefCell::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let cycle_b = Rc::new(RefCell::new(CyclicDataStructure {
        data: 1_u32,
        next: None,
    }));
    let cycle_c = Rc::new(RefCell::new(CyclicDataStructure {
        data: 2_u32,
        next: None,
    }));

    cycle_a.borrow_mut().insert_next(cycle_b.clone());
    cycle_b.borrow_mut().insert_next(cycle_c.clone());
    cycle_c.borrow_mut().insert_next(cycle_a.clone());

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = RefCellRefMutStack::new(&cycle_a).expect("not mutable borrowed yet");
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let Err(_borrow_error) = stack
            .descend_with(CyclicDataStructure::next)
            .expect("no node has no next")
        {
            println!("Found a cycle!");
            break;
        }
        println!("Descended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }
    println!("Stack currently at item with value: {}", stack.top().data);
    loop {
        if let None = stack.ascend() {
            println!("Reached the head of the linked list!");
            break;
        }
        println!("Ascended successfully!");
        println!("Stack currently at item with value: {}", stack.top().data);
    }

    println!("(Breaking the cycle to prevent miri from complaining about memory leaks)");
    stack.top_mut().take_next();
}

pub fn ascend_while<P>(&mut self, predicate: P) -> &mut T

where P: FnMut(&mut T) -> bool,

Ascend back up from the recursive data structure while the given closure returns true, returning a mutable reference to the new top element. If we are not currently at the root, and the predicate returns true, ascend and continue. If we are already at the root, or if the predicate returned false, returns a reference to the top element.

pub fn move_with<F>(&mut self, f: F) -> Result<&mut T, MoveError>

where F: for<'a> FnOnce(&'a mut T) -> MoveDecision<'root, 'a, T>,

Ascend from, descend from, inject a new stack top, or stay at the current node, based on the return value of the closure.

pub async fn move_with_async<F>(&mut self, f: F) -> Result<&mut T, MoveError>

where F: for<'a> FnOnce(&'a mut T) -> Pin<Box<dyn Future<Output = MoveDecision<'root, 'a, T>> + 'a>>,

pub fn into_top(self) -> RefMut<'root, T>

Return reference to the top element of this stack, forgetting about the stack entirely. Note that this leaks all RefMuts above the top.

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

Pop all RefMuts off the stack and go back to the root.

Trait Implementations

impl<'root, T: ?Sized> Drop for RefCellRefMutStack<'root, T>

fn drop(&mut self)

Executes the destructor for this type.