Struct owning_ref::OwningHandle

pub struct OwningHandle<O, H> where
    O: StableAddress,
    H: Deref,  { /* fields omitted */ }

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.

OwningHandle can encapsulate a RefMut along with its associated RefCell, or an RwLockReadGuard along with its associated RwLock. However, the API is completely generic and there are no restrictions on what types of owning and dependent objects may be used.

OwningHandle is created by passing an owner object (which dereferences to a stable address) along with a callback which receives a pointer to that stable location. The callback may then dereference the pointer and mint a dependent object, with the guarantee that the returned object will not outlive the referent of the pointer.

This does foist some unsafety onto the callback, which needs an unsafe block to dereference the pointer. It would be almost good enough for OwningHandle to pass a transmuted &’statc reference to the callback since the lifetime is infinite as far as the minted handle is concerned. However, even an Fn callback can still allow the reference to escape via a StaticMutex or similar, which technically violates the safety contract. Some sort of language support in the lifetime system could make this API a bit nicer.

Implementations

impl<O, H> OwningHandle<O, H> where
    O: StableAddress,
    H: Deref, 

pub fn new<F>(o: O, f: F) -> Self where
    F: Fn(*const O::Target) -> H, 

Create a new OwningHandle. The provided callback will be invoked with a pointer to the object owned by o, and the returned value is stored as the object to which this OwningHandle will forward Deref and DerefMut.

pub fn try_new<F, E>(o: O, f: F) -> Result<Self, E> where
    F: Fn(*const O::Target) -> Result<H, E>, 

Create a new OwningHandle. The provided callback will be invoked with a pointer to the object owned by o, and the returned value is stored as the object to which this OwningHandle will forward Deref and DerefMut.

Trait Implementations

impl<O, H> Deref for OwningHandle<O, H> where
    O: StableAddress,
    H: Deref, 

type Target = H::Target

The resulting type after dereferencing.

fn deref(&self) -> &H::Target

Dereferences the value.

impl<O, H> DerefMut for OwningHandle<O, H> where
    O: StableAddress,
    H: DerefMut, 

fn deref_mut(&mut self) -> &mut H::Target

Mutably dereferences the value.

impl<O, H> StableAddress for OwningHandle<O, H> where
    O: StableAddress,
    H: StableAddress,