Struct MutexGuardStack 

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

Implementations

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

pub fn new(root: &'root Mutex<T>) -> TryLockResult<Self>

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

Examples found in repository

examples/cyclic_sync.rs (line 39)

fn main() {
    let cycle_root = Arc::new(Mutex::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let mut current = cycle_root.clone();
    for i in (1..128).rev() {
        current = Arc::new(Mutex::new(CyclicDataStructure {
            data: i,
            next: Some(current),
        }))
    }
    cycle_root.lock().unwrap().next = Some(current);

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = MutexGuardStack::new(&cycle_root).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, false)
            .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_sync.rs (line 40)

fn main() {
    let cycle_root = Arc::new(Mutex::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let mut current = cycle_root.clone();
    for i in (1..128).rev() {
        current = Arc::new(Mutex::new(CyclicDataStructure {
            data: i,
            next: Some(current),
        }))
    }
    cycle_root.lock().unwrap().next = Some(current);

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = MutexGuardStack::new(&cycle_root).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, false)
            .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_sync.rs (line 63)

fn main() {
    let cycle_root = Arc::new(Mutex::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let mut current = cycle_root.clone();
    for i in (1..128).rev() {
        current = Arc::new(Mutex::new(CyclicDataStructure {
            data: i,
            next: Some(current),
        }))
    }
    cycle_root.lock().unwrap().next = Some(current);

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = MutexGuardStack::new(&cycle_root).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, false)
            .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 Mutex<T>, ignore_poison: bool, ) -> Result<&mut T, TryLockError<()>>

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 Mutex<T>>, ignore_poison: bool, ) -> Option<Result<&mut T, TryLockError<()>>>

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 Mutex<T>>, ignore_poison: bool, ) -> Option<Result<&mut T, TryLockError<()>>>

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_sync.rs (line 43)

fn main() {
    let cycle_root = Arc::new(Mutex::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let mut current = cycle_root.clone();
    for i in (1..128).rev() {
        current = Arc::new(Mutex::new(CyclicDataStructure {
            data: i,
            next: Some(current),
        }))
    }
    cycle_root.lock().unwrap().next = Some(current);

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = MutexGuardStack::new(&cycle_root).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, false)
            .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_sync.rs (line 54)

fn main() {
    let cycle_root = Arc::new(Mutex::new(CyclicDataStructure {
        data: 0_u32,
        next: None,
    }));
    let mut current = cycle_root.clone();
    for i in (1..128).rev() {
        current = Arc::new(Mutex::new(CyclicDataStructure {
            data: i,
            next: Some(current),
        }))
    }
    cycle_root.lock().unwrap().next = Some(current);

    // Using a MutRefStack to descend *and then ascend* the data structure.
    // This cannot be done with regular mutable references.
    let mut stack = MutexGuardStack::new(&cycle_root).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, false)
            .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, ignore_poison: bool, ) -> 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, ignore_poison: bool, ) -> 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) -> MutexGuard<'root, T>

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

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

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

Trait Implementations

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

fn drop(&mut self)

Executes the destructor for this type.