Struct own_ref::OwnRef

pub struct OwnRef<'slot, T: 'slot + ?Sized, DropFlags: 'static = No> { /* private fields */ }

&'slot own T.

Implementations

impl<'slot, T> OwnRef<'slot, T>

pub fn deref_move(self: OwnRef<'slot, T>) -> T

Perform a “deref-move” operation akin to * on Boxes.

Same API as OwnRef::into_inner(), but with some more panache.

impl<'slot, T> OwnRef<'slot, T>

pub unsafe fn from_ref_unchecked( r: &'slot mut ManuallyDrop<T> ) -> OwnRef<'slot, T, No>

Low-level OwnRef construction.

An OwnRef<'slot, T>, at least, one with No DropFlags attached, is “merely” a “glorified” &'slot mut ManuallyDrop<T>, with an automatic ManuallyDrop::drop() invocation engrained into its Drop glue, and thus, raison d’être.

• From there, it grows to become way more than that, thanks to its unsizing capabilities, which in turn subsume whole language features such as #![feature(unsized_fn_params)], or even #![feature(unsized_rvalues)] altogether.

It thus makes sense for such a basic and quintessential construction to be available.

Do note that the Pin-related APIs and types, such as OwnRef<'_, T, DropFlags::Yes>, are more involved and subtle than this, with (raw) pointer provenance playing an important role. Try to steer away from unsafely constructing that type.

Safety

Calling this returns a handle which, ultimately, calls ManuallyDrop::drop() (or ManuallyDrop::take() if calling OwnRef::deref_move()), so necessarily, the safety requirements and caveats of these ManuallyDrop APIs apply.

Good news is, they also suffice.

impl<'slot, T> OwnRef<'slot, T>

pub fn with<R>(value: T, scope: impl FnOnce(OwnRef<'_, T>) -> R) -> R

Simple, albeit limited, OwnRef constructor, through a scoped API.

Using own_ref! will, most of the time, result in a more flexible and pleasant API.

Example

use ::own_ref::*;

let x = OwnRef::with(String::from("…"), |o: OwnRef<'_, String>| {
    assert_eq!(&o[..], "…");
    42
});
assert_eq!(x, 42);

impl<'slot, T: ?Sized, D> OwnRef<'slot, T, D>

pub unsafe fn from_raw( ptr: *mut ManuallyDrop<T>, _you_can_use_this_to_bound_the_lifetime: [&'slot (); 0] ) -> OwnRef<'slot, T, D>

Construct a Self out of a &'slot mut ManuallyDrop<T>.

• (Consider the arg pair as acting as one).

Safety

0. Casting the ptr to a &'slot mut ManuallyDrop<T> must be sound.

1. Since the resulting pointer has ownership over the pointee T, i.e., since T is to be dropped by Self, then ManuallyDrop::take() (and/or ManuallyDrop::drop()) requirements fully apply.

2. D ought not to be pin::DropFlags::Yes.

   If it is, then careful with variance! Also, ptr must be pointing to the .value field of a pin::ManualOption, with exclusive write provenance over the whole ManualOption.

   • (currently that field is not exposed at all publicly since it is a very finicky requirement).

pub fn into_raw( self: OwnRef<'slot, T, D> ) -> (*mut ManuallyDrop<T>, [&'slot (); 0])

Converts the OwnRef back into its constituent raw pointer, disabling the Drop glue, and whatnot.

The returned pair is conceptually equivalent to a &'slot ManuallyDrop<T>, but the usage of a raw pointer avoids shrinking provenance of the pointer, which matters when D is DropFlags::Yes.

impl<'slot, T> OwnRef<'slot, T, Yes>

pub fn with_pinned<R>( value: T, scope: impl FnOnce(Pin<OwnRef<'_, T, Yes>>) -> R ) -> R

Same as OwnRef::with(), but for the value being Pinned.

Uses runtime drop flags to guard against improper memory leakage, lest unsoundness ensue.

impl<'slot, T: ?Sized> OwnRef<'slot, T>

pub fn downcast<U>( self: OwnRef<'slot, T> ) -> Result<OwnRef<'slot, U>, OwnRef<'slot, T>>

where T: Any, U: Any,

The moral equivalent of Box::downcast, but for OwnRefs.

More like .owncast(), am I right? 🥁

Example

#![forbid(unsafe_code)]

use ::core::any::{Any, TypeId};
use ::own_ref::prelude::*;

fn too_generic<T : 'static>(it: T) {
    // Say we want to do something special if `T` is a `String`.

    match own_ref!(: T = it).downcast::<String>() {
        // Ok, `T = String` here, and this property is embodied
        // by `s: &own String` in this branch:
        Ok(own_s) => {
            let s: String = own_s.deref_move();
            // …
        },
        Err(own_t) => {
            let it: T = own_t.deref_move();
        },
    }
}

Trait Implementations

impl<'slot, D, T: Debug> Debug for OwnRef<'slot, T, D>

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

Formats the value using the given formatter.

impl<'slot, T: ?Sized, D> Deref for OwnRef<'slot, T, D>

type Target = T

The resulting type after dereferencing.

fn deref(self: &OwnRef<'slot, T, D>) -> &T

Dereferences the value.

impl<'slot, T: ?Sized, D> DerefMut for OwnRef<'slot, T, D>

fn deref_mut(self: &mut OwnRef<'slot, T, D>) -> &mut T

Mutably dereferences the value.

impl<'slot, T: ?Sized, DropFlags> Drop for OwnRef<'slot, T, DropFlags>

fn drop(&mut self)

Executes the destructor for this type.

impl<'slot, Args, F: ?Sized + FnOwn<Args>> FnOwn<Args> for OwnRef<'slot, F>

fn call_ownref(self, args: Args) -> Self::Ret

The moral equivalent of extern "rust-call" fn call_once.

fn call_ownref_1<_0>(self, _0: _0) -> Self::Ret

where Self: Sized, (_0,): Is<ItSelf = Args>,

Convenience sugar around Self::call_ownref().

fn call_ownref_11<_10, _9, _8, _7, _6, _5, _4, _3, _2, _1, _0>( self, _10: _10, _9: _9, _8: _8, _7: _7, _6: _6, _5: _5, _4: _4, _3: _3, _2: _2, _1: _1, _0: _0 ) -> Self::Ret

where Self: Sized, (_10, _9, _8, _7, _6, _5, _4, _3, _2, _1, _0): Is<ItSelf = Args>,

Convenience sugar around Self::call_ownref().

impl<'slot, Args, F: ?Sized + FnOwn<Args>> FnOwnRet<Args> for OwnRef<'slot, F>

type Ret = <F as FnOwnRet<Args>>::Ret

impl<'slot, T: ?Sized, D> RefUnwindSafe for OwnRef<'_, T, D>

where (&'slot mut [MU<u8>], T): RefUnwindSafe,

impl<'slot, T: ?Sized, D> Send for OwnRef<'_, T, D>

where (&'slot mut [MU<u8>], T): Send,

impl<'slot, T: ?Sized, D> Sync for OwnRef<'_, T, D>

where (&'slot mut [MU<u8>], T): Sync,

impl<'slot, T: ?Sized, D> Unpin for OwnRef<'slot, T, D>

where &'slot mut T: Unpin,

impl<'slot, T: ?Sized, D> UnwindSafe for OwnRef<'_, T, D>

where (&'slot mut [MU<u8>], T): UnwindSafe,