[][src]Crate owning_ref

An owning reference.

This crate provides the owning reference types OwningRef and OwningRefMut that enables it to bundle a reference together with the owner of the data it points to. This allows moving and dropping of a OwningRef without needing to recreate the reference.

This can sometimes be useful because Rust borrowing rules normally prevent moving a type that has been moved from. For example, this kind of code gets rejected:

This example is not tested
fn return_owned_and_referenced<'a>() -> (Vec<u8>, &'a [u8]) {
    let v = vec![1, 2, 3, 4];
    let s = &v[1..3];
    (v, s)
}

Even though, from a memory-layout point of view, this can be entirely safe if the new location of the vector still lives longer than the lifetime 'a of the reference because the backing allocation of the vector does not change.

This library enables this safe usage by keeping the owner and the reference bundled together in a wrapper type that ensure that lifetime constraint:

fn return_owned_and_referenced() -> OwningRef<Vec<u8>, [u8]> {
    let v = vec![1, 2, 3, 4];
    let or = OwningRef::new(v);
    let or = or.map(|v| &v[1..3]);
    or
}

It works by requiring owner types to dereference to stable memory locations and preventing mutable access to root containers, which in practice requires heap allocation as provided by Box<T>, Rc<T>, etc.

Also provided are typedefs for common owner type combinations, which allow for less verbose type signatures. For example, BoxRef<T> instead of OwningRef<Box<T>, T>.

The crate also provides the more advanced OwningHandle type, which allows more freedom in bundling a dependent handle object along with the data it depends on, at the cost of some unsafe needed in the API. See the documentation around OwningHandle for more details.

Examples

Basics

extern crate owning_ref;
use owning_ref::BoxRef;

fn main() {
    // Create an array owned by a Box.
    let arr = Box::new([1, 2, 3, 4]) as Box<[i32]>;

    // Transfer into a BoxRef.
    let arr: BoxRef<[i32]> = BoxRef::new(arr);
    assert_eq!(&*arr, &[1, 2, 3, 4]);

    // We can slice the array without losing ownership or changing type.
    let arr: BoxRef<[i32]> = arr.map(|arr| &arr[1..3]);
    assert_eq!(&*arr, &[2, 3]);

    // Also works for Arc, Rc, String and Vec!
}

Caching a reference to a struct field

extern crate owning_ref;
use owning_ref::BoxRef;

fn main() {
    struct Foo {
        tag: u32,
        x: u16,
        y: u16,
        z: u16,
    }
    let foo = Foo { tag: 1, x: 100, y: 200, z: 300 };

    let or = BoxRef::new(Box::new(foo)).map(|foo| {
        match foo.tag {
            0 => &foo.x,
            1 => &foo.y,
            2 => &foo.z,
            _ => panic!(),
        }
    });

    assert_eq!(*or, 200);
}

Caching a reference to an entry in a vector

extern crate owning_ref;
use owning_ref::VecRef;

fn main() {
    let v = VecRef::new(vec![1, 2, 3, 4, 5]).map(|v| &v[3]);
    assert_eq!(*v, 4);
}

Caching a subslice of a String

extern crate owning_ref;
use owning_ref::StringRef;

fn main() {
    let s = StringRef::new("hello world".to_owned())
        .map(|s| s.split(' ').nth(1).unwrap());

    assert_eq!(&*s, "world");
}

Reference counted slices that share ownership of the backing storage

extern crate owning_ref;
use owning_ref::RcRef;
use std::rc::Rc;

fn main() {
    let rc: RcRef<[i32]> = RcRef::new(Rc::new([1, 2, 3, 4]) as Rc<[i32]>);
    assert_eq!(&*rc, &[1, 2, 3, 4]);

    let rc_a: RcRef<[i32]> = rc.clone().map(|s| &s[0..2]);
    let rc_b = rc.clone().map(|s| &s[1..3]);
    let rc_c = rc.clone().map(|s| &s[2..4]);
    assert_eq!(&*rc_a, &[1, 2]);
    assert_eq!(&*rc_b, &[2, 3]);
    assert_eq!(&*rc_c, &[3, 4]);

    let rc_c_a = rc_c.clone().map(|s| &s[1]);
    assert_eq!(&*rc_c_a, &4);
}

Atomic reference counted slices that share ownership of the backing storage

extern crate owning_ref;
use owning_ref::ArcRef;
use std::sync::Arc;

fn main() {
    use std::thread;

    fn par_sum(rc: ArcRef<[i32]>) -> i32 {
        if rc.len() == 0 {
            return 0;
        } else if rc.len() == 1 {
            return rc[0];
        }
        let mid = rc.len() / 2;
        let left = rc.clone().map(|s| &s[..mid]);
        let right = rc.map(|s| &s[mid..]);

        let left = thread::spawn(move || par_sum(left));
        let right = thread::spawn(move || par_sum(right));

        left.join().unwrap() + right.join().unwrap()
    }

    let rc: Arc<[i32]> = Arc::new([1, 2, 3, 4]);
    let rc: ArcRef<[i32]> = rc.into();

    assert_eq!(par_sum(rc), 10);
}

References into RAII locks

extern crate owning_ref;
use owning_ref::RefRef;
use std::cell::{RefCell, Ref};

fn main() {
    let refcell = RefCell::new((1, 2, 3, 4));
    // Also works with Mutex and RwLock

    let refref = {
        let refref = RefRef::new(refcell.borrow()).map(|x| &x.3);
        assert_eq!(*refref, 4);

        // We move the RAII lock and the reference to one of
        // the subfields in the data it guards here:
        refref
    };

    assert_eq!(*refref, 4);

    drop(refref);

    assert_eq!(*refcell.borrow(), (1, 2, 3, 4));
}

Mutable reference

When the owned container implements DerefMut, it is also possible to make a mutable owning reference. (E.g. with Box, RefMut, MutexGuard)

extern crate owning_ref;
use owning_ref::RefMutRefMut;
use std::cell::{RefCell, RefMut};

fn main() {
    let refcell = RefCell::new((1, 2, 3, 4));

    let mut refmut_refmut = {
        let mut refmut_refmut = RefMutRefMut::new(refcell.borrow_mut()).map_mut(|x| &mut x.3);
        assert_eq!(*refmut_refmut, 4);
        *refmut_refmut *= 2;

        refmut_refmut
    };

    assert_eq!(*refmut_refmut, 8);
    *refmut_refmut *= 2;

    drop(refmut_refmut);

    assert_eq!(*refcell.borrow(), (1, 2, 3, 16));
}

Structs

OwningHandle

OwningHandle is a complement to OwningRef. Where OwningRef allows consumers to pass around an owned object and a dependent reference, OwningHandle contains an owned object and a dependent object.

OwningRef

An owning reference.

OwningRefMut

An mutable owning reference.

Traits

CloneStableAddress

An unsafe marker trait for types where clones deref to the same address. This has all the requirements of StableDeref, and additionally requires that after calling clone(), both the old and new value deref to the same address. For example, Rc and Arc implement CloneStableDeref, but Box and Vec do not.

Erased

Helper trait for an erased concrete type an owner dereferences to. This is used in form of a trait object for keeping something around to (virtually) call the destructor.

IntoErased

Helper trait for erasing the concrete type of what an owner derferences to, for example Box<T> -> Box<dyn Erased>. This would be unneeded with higher kinded types support in the language.

StableAddress

An unsafe marker trait for types that deref to a stable address, even when moved. For example, this is implemented by Box, Vec, Rc, Arc and String, among others. Even when a Box is moved, the underlying storage remains at a fixed location.

ToHandle

Trait to implement the conversion of owner to handle for common types.

ToHandleMut

Trait to implement the conversion of owner to mutable handle for common types.

Type Definitions

ArcRef

Typedef of a owning reference that uses a Arc as the owner.

BoxRef

Typedef of a owning reference that uses a Box as the owner.

BoxRefMut

Typedef of a mutable owning reference that uses a Box as the owner.

ErasedArcRef

Typedef of a owning reference that uses an erased Arc as the owner.

ErasedBoxRef

Typedef of a owning reference that uses an erased Box as the owner.

ErasedBoxRefMut

Typedef of a mutable owning reference that uses an erased Box as the owner.

ErasedRcRef

Typedef of a owning reference that uses an erased Rc as the owner.

MutexGuardRef

Typedef of a owning reference that uses a MutexGuard as the owner.

MutexGuardRefMut

Typedef of a mutable owning reference that uses a MutexGuard as the owner.

RcRef

Typedef of a owning reference that uses a Rc as the owner.

RefMutRef

Typedef of a owning reference that uses a RefMut as the owner.

RefMutRefMut

Typedef of a mutable owning reference that uses a RefMut as the owner.

RefRef

Typedef of a owning reference that uses a Ref as the owner.

RwLockReadGuardRef

Typedef of a owning reference that uses a RwLockReadGuard as the owner.

RwLockWriteGuardRef

Typedef of a owning reference that uses a RwLockWriteGuard as the owner.

RwLockWriteGuardRefMut

Typedef of a mutable owning reference that uses a RwLockWriteGuard as the owner.

StringRef

Typedef of a owning reference that uses a String as the owner.

StringRefMut

Typedef of a mutable owning reference that uses a String as the owner.

VecRef

Typedef of a owning reference that uses a Vec as the owner.

VecRefMut

Typedef of a mutable owning reference that uses a Vec as the owner.