Struct RwAnchor

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

An !Send mutable anchor with overlapping immutable borrows. Use this to capture mutable references in a single-threaded environment.

Deadlocks

Iff there is a currently active borrow, then dropping this anchor will cause a deadlock as last resort measure to prevent UB:

use ref_portals::rc::RwAnchor;

let mut x = "Scoped".to_owned();
let anchor = RwAnchor::new(&mut x);
let portal = anchor.portal();
let _guard = portal.borrow();

assert_deadlock!(drop(anchor), Duration::from_secs(1));

Panics

On drop, if any associated RwPortals exist:

use ref_portals::rc::RwAnchor;

let mut x = "Scoped".to_owned();
let anchor = RwAnchor::new(&mut x);
Box::leak(Box::new(anchor.portal()));

assert_panic!(
    drop(anchor),
    &str,
    "Anchor still in use (at least one portal exists)",
);

Otherwise, on drop, iff the anchor has been poisoned:

use ref_portals::rc::RwAnchor;

let mut x = "Scoped".to_owned();
let anchor = RwAnchor::new(&mut x);
{
    let portal = anchor.portal();
    assert_panic!({
        let guard = portal.borrow_mut();
        panic!()
    });
}

assert_panic!(
    drop(anchor),
    &str,
    "Anchor poisoned",
);

Implementations

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

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

Creates a new RwAnchor instance, capturing reference.

pub fn portal(&self) -> RwPortal<T>

Creates a fallible portal with unbounded lifetime supporting overlapping reads.

Example

let mut x = "Scoped".to_owned();
let anchor = RwAnchor::new(&mut x);
let self_owned: Box<dyn Fn() + 'static> = Box::new({
    let portal = anchor.portal();
    move || {
        println!("{}", *portal.borrow());
        *portal.borrow_mut() = "Replacement".to_owned();
    }
});

self_owned(); // Scoped
drop(self_owned);
drop(anchor);
println!("{}", x); // Replacement

pub fn weak_portal(&self) -> WeakRwPortal<T>

Trait Implementations

impl<'a, T: Debug + ?Sized> Debug for RwAnchor<'a, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, T: ?Sized> Drop for RwAnchor<'a, T>

fn drop(&mut self)

Executes the destructor for this type.

Panics

If any associated RwPortals exist or, otherwise, iff the anchor has been poisoned:

use ref_portals::rc::RwAnchor;

let mut x = "Scoped".to_owned();
let anchor = RwAnchor::new(&mut x);
let portal = anchor.portal();
assert_panic!({
    // Poison anchor.
    let _guard = portal.borrow_mut();
    panic!()
});

assert_panic!(
    drop(anchor),
    &str,
    "Anchor still in use (at least one portal exists)",
);

impl<'a, T> UnwindSafe for RwAnchor<'a, T>

where T: RefUnwindSafe + ?Sized,

Safety:

use ref_portals::rc::RwAnchor;

let mut x = "Scoped".to_owned();
let anchor = RwAnchor::new(&mut x);
let portal = anchor.portal();

assert_panic!(
    drop(anchor),
    &str,
    "Anchor still in use (at least one portal exists)",
);
assert_panic!(
    { portal.borrow_mut(); },
    &str,
    "Anchor poisoned",
);