Struct MoveRef

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

A “reference” type which uniquely owns its referent type T with respect to external storage with lifetime 'frame.

Conceptually, it has these characteristics:

• similar to &'frame mut because it uniquely references other data with lifetime 'frame
• similar to Box because it is owning

The distinguishing characteristic of MoveRef from &mut and Box is how it is created with a backing storage Slot and how that defines its ownership of the referent data, and ultimately how the backing storage is responsible for running the destructor for its referent when it finally goes out of scope.

A motivating example for MoveRef is the concept of placement-initialization in C++:

Imagine we define FFI bindings for a C++ class we intend to use in Rust.

Creating instances for this class on the heap is straightforward and well understood: we can use raw pointers and eventually either convert to a reference or Box.

Creating instances for this class on the stack is more difficult. We can use MaybeUninit to create a chunk of data and initialize into that.

But we have to be particularly careful when using the result because in Rust, data moves by default, rather than copies by default as in C++. So any access of the data in Rust could potentially move the data out from under some expected location in C++ and cause a crash when execution proceeds again in C++.

So we need a type which acts like a (mutable) reference but does not let us move simply by accessing it. This would be similar to a Pin<&mut T>, where the Pin prevents movement, but the inner &mut still allows mutation.

But we also want the possibility to actually move the data in some cases, like we would explicitly do in C++ with a move constructor or move assignment operation.

This interface is exactly what MoveRef provides, along with DerefMove.

Implementations

impl<'frame, T: ?Sized> MoveRef<'frame, T>

pub fn into_pin(self) -> Pin<Self>

Transform a MoveRef<T> into a Pin<MoveRef<T>>. This is safe because the interface for MoveRef enforces that its referent will not be implicitly moved or have its storage invalidated until the MoveRef<T> (and its backing Slot) is dropped.

pub fn release(pin: Pin<Self>) -> *mut T

Consume a Pin<Self> and return a raw *mut T. This operation inhibits destruction of T by implicit Drop and the caller becomes responsible for eventual explicit destruction and cleanup, otherwise the memory will leak.

impl<'frame, T> MoveRef<'frame, T>

pub fn into_inner(self) -> T

pub fn as_ptr(&self) -> *const T

pub fn as_mut_ptr(&mut self) -> *mut T

Trait Implementations

impl<'frame, T> Debug for MoveRef<'frame, T>

where T: Debug + ?Sized,

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

Formats the value using the given formatter.

impl<T: ?Sized> Deref for MoveRef<'_, T>

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

impl<'f, T: ?Sized> DerefMove for MoveRef<'f, T>

fn deref_move<'frame>( self, _storage: Slot<'frame, Self::Storage>, ) -> MoveRef<'frame, Self::Target>

where Self: 'frame,

Construct a MoveRef by dereferencing self and moving its contents into storage.

impl<T: ?Sized> DerefMut for MoveRef<'_, T>

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

Mutably dereferences the value.

impl<T: ?Sized> Drop for MoveRef<'_, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'t, T> Hash for MoveRef<'t, T>

where T: Hash + ?Sized,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'f, T: ?Sized> IntoMove for MoveRef<'f, T>

type Storage = ()

fn into_move<'frame>( self, storage: Slot<'frame, Self::Storage>, ) -> Pin<MoveRef<'frame, Self::Target>>

where Self: 'frame,

Consume self and create a pinned MoveRef with self’s contents placed into storage.

impl<'t, T> Ord for MoveRef<'t, T>

where T: Ord,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'s, 't, S, T> PartialEq<MoveRef<'s, S>> for MoveRef<'t, T>

where T: PartialEq<S> + ?Sized,

fn eq(&self, other: &MoveRef<'s, S>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'s, 't, S, T> PartialOrd<MoveRef<'s, S>> for MoveRef<'t, T>

where T: PartialOrd<S> + ?Sized,

fn partial_cmp(&self, other: &MoveRef<'s, S>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &MoveRef<'s, S>) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &MoveRef<'s, S>) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &MoveRef<'s, S>) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &MoveRef<'s, S>) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'t, T> Eq for MoveRef<'t, T>

where T: PartialEq,