Struct recursive_reference::RecRef

pub struct RecRef<'a, T: ?Sized> { /* fields omitted */ }

A Recursive reference. This struct is used to allow recursively reborrowing mutable references in a dynamic but safe way.

Implementations

impl<'a, T: ?Sized> RecRef<'a, T>

pub fn new(r: &'a mut T) -> Self

pub fn size(&self) -> usize

pub fn extend<F>(&mut self, func: F) where
    F: for<'b> FnOnce(&'b mut T) -> &'b mut T, 

This function extends the RecRef one time. That means, if the current reference is current_ref: &mut T, then this call extends the RecRef with the new reference ref2: &mut T = func(current_ref). After this call, the RecRef will expose the new ref2, and current_ref will be frozen (As it is borrowed by ref2), until ref2 is popped off, unfreezing current_ref.

Safety:

The type ensures no leaking is possible, since func can’t guarantee that current_ref will live for any length of time, so it can’t leak it anywhere. It can only use current_ref inside the function, and use it in order to return ref2, which is the intended usage.

A different point of view is this: we have to borrow current_ref to func with the actual correct lifetime: the lifetime in which it is allowed to freeze current_ref in order to use ref2.

However, we don’t know yet what that lifetime is: it will be whatever amount of time passes until ref2 will be popped back, unfreezing current_ref. (and that lifetime can even be decided dynamically). Whatever lifetime 'freeze_time that turns out to be, the type of func should have been func: FnOnce(&'freeze_time mut T) -> &'freeze_time mut T.

Therefore, we require that func will be able to work with any value of 'freeze_time, so we are sure that the code would’ve worked correctly if we put the correct lifetime there. So that ensures the code is safe.

Another point of view is considering what other types we could have given to this function: If the type was just

fn extend<'a, F : FnOnce(&'a mut T) -> &'a mut T>(&mut self, func : F)

then this function would be unsafe, because func could leak the reference outside, and then the caller could immediately pop the RecRef to get another copy of the same reference.

We could use

fn extend<'a, F : FnOnce(&'a mut T) -> &'a mut T>(&'a mut self, func : F)

But that would invalidate the whole point of using the RecRef - You couldn’t use it after extending even once, and it couldn’t be any better than a regular mutable reference.

pub fn extend_result<E, F>(&mut self, func: F) -> Result<(), E> where
    F: for<'b> FnOnce(&'b mut T) -> Result<&'b mut T, E>, 

Same as Self::extend, but allows the function to return an error value.

pub fn extend_result_precise<E, F>(&mut self, func: F) -> Result<(), E> where
    F: for<'b> FnOnce(&'b mut T, PhantomData<&'b &'a ()>) -> Result<&'b mut T, E>, 

Same as Self::extend, but allows the function to return an error value, and also tells the inner function that 'a : 'b using a phantom argument.

pub fn map<F>(&mut self, func: F) where
    F: for<'b> FnOnce(&'b mut T) -> &'b mut T, 

This function maps the top of the RecRef. It’s similar to Self::extend, but it replaces the current reference instead of keeping it. See Self::extend for more details.

pub fn map_result<E, F>(&mut self, func: F) -> Result<(), E> where
    F: for<'b> FnOnce(&'b mut T) -> Result<&'b mut T, E>, 

Same as Self::map, but allows the function to return an error value.

pub fn map_result_precise<E, F>(&mut self, func: F) -> Result<(), E> where
    F: for<'b> FnOnce(&'b mut T, PhantomData<&'b &'a ()>) -> Result<&'b mut T, E>, 

Same as Self::map, but allows the function to return an error value, and also tells the inner function that 'a : 'b using a phantom argument.

pub fn push(&mut self, r: &'a mut T)

Push another reference to the RecRef, unrelated to the current one. rec_ref.push(new_ref) is morally equivalent to rec_ref.extend_result_precise(move |_, _| { Ok(new_ref) }). However, you might have some trouble making the anonymous function conform to the right type.

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

Lets the user use the last reference for some time, and discards it completely. After the user uses it, the next time they inspect the RecRef, it won’t be there. Can’t pop the last reference, as the RecRef can’t be empty, and returns None instead.

pub fn into_ref(self) -> &'a mut T

Discards the RecRef and returns the last reference. The difference between this and using Self::pop are:

• This will consume the RecRef
• Self::pop will never pop the first original reference, because that would produce an invalid RecRef. Self::into_ref will.

pub fn get_nonnull(&self, i: usize) -> NonNull<T>

Gets the std::ptr::NonNull pointer that is i’th from the top of the RecRef. The intended usage is for using the pointers as the inputs to ptr_eq. However, using the pointers themselves (which requires unsafe) will almost definitely break rust’s guarantees.

Trait Implementations

impl<'a, T: ?Sized> Deref for RecRef<'a, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'a, T: ?Sized> DerefMut for RecRef<'a, T>

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

Mutably dereferences the value.

impl<'a, T: ?Sized> From<&'a mut T> for RecRef<'a, T>

fn from(r: &'a mut T) -> Self

Performs the conversion.