Struct abi_stable::sabi_types::MovePtr

pub struct MovePtr<'a, T> { /* private fields */ }

A move pointer, which allows moving the value from the reference, consuming it in the process.

If MovePtr::into_inner isn’t called, this drops the referenced value when it’s dropped

Safety

This is unsafe to construct since the user must ensure that the original owner of the value never accesses it again.

Motivation

MovePtr was created as a way to pass self by value to ffi-safe trait object methods, since one can’t simply pass self by value(because the type is erased).

Examples

Using OwnedPointer::in_move_ptr

This is how one can use MovePtr without unsafe.

This simply moves the contents of an RBox<T> into a Box<T>.

use abi_stable::{
    pointer_trait::OwnedPointer, sabi_types::MovePtr, std_types::RBox,
};

fn move_rbox_to_box<T>(rbox: RBox<T>) -> Box<T> {
    rbox.in_move_ptr(|move_ptr| MovePtr::into_box(move_ptr))
}

assert_eq!(move_rbox_to_box(RBox::new(99)), Box::new(99));

assert_eq!(move_rbox_to_box(RBox::new(())), Box::new(()));

assert_eq!(
    move_rbox_to_box(RBox::new(String::from("SHIT"))),
    Box::new(String::from("SHIT"))
);

Using the (unsafe) MovePtr::new

This is (sort of) how RBox<T> implements moving the T it owns out of its allocation

This is basically what OwnedPointer::{with_move_ptr,in_move_ptr} do.

use abi_stable::{
    pointer_trait::{AsMutPtr, OwnedPointer},
    sabi_types::MovePtr,
    std_types::RBox,
};

use std::mem::ManuallyDrop;

let rbox = RBox::new(0x100);

let second_rbox;

unsafe {
    let mut rbox = ManuallyDrop::new(rbox);

    let move_ptr = unsafe { MovePtr::from_rmut(rbox.as_rmut()) };
    second_rbox = RBox::from_move_ptr(move_ptr);

    OwnedPointer::drop_allocation(&mut rbox);
}

assert_eq!(second_rbox, RBox::new(0x100));

Implementations

impl<'a, T> MovePtr<'a, T>

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

Constructs this move pointer from a mutable reference, moving the value out of the reference.

Safety

Callers must ensure that the original owner of the value won’t access the moved-out value anymore.

Example

use abi_stable::sabi_types::MovePtr;

use std::mem::ManuallyDrop;

let mut manual = ManuallyDrop::new(String::from("hello"));

let moveptr = unsafe { MovePtr::new(&mut *manual) };

drop(moveptr); // moveptr drops the String here.

pub const unsafe fn from_rmut(ptr: RMut<'a, T>) -> Self

Constructs this move pointer from an RMut, moving the value out of the reference.

Safety

Callers must ensure that the original owner of the value won’t access the moved-out value anymore.

Example

use abi_stable::{
    pointer_trait::AsMutPtr, sabi_types::MovePtr, std_types::RString,
    utils::manuallydrop_as_rmut,
};

use std::mem::ManuallyDrop;

let mut mdrop = ManuallyDrop::new(RString::from("hello"));

// safety: `mdrop` is never accessed again
let moveptr = unsafe { MovePtr::from_rmut(manuallydrop_as_rmut(&mut mdrop)) };
assert_eq!(*moveptr, "hello");

let string: RString = MovePtr::into_inner(moveptr);
assert_eq!(string, "hello");

pub const unsafe fn from_raw(ptr: *mut T) -> Self

Constructs this move pointer from a raw pointer, moving the value out of it.

Safety

Callers must ensure that the original owner of the value won’t access the moved-out value anymore.

Because this takes a mutable pointer, the lifetime of this MovePtr is unbounded. You must ensure that it’s not used for longer than the lifetime of the pointed-to value.

Example

use abi_stable::{
    pointer_trait::AsMutPtr, rvec, sabi_types::MovePtr, std_types::RVec,
    utils::manuallydrop_as_raw_mut,
};

use std::mem::ManuallyDrop;

let mut mdrop = ManuallyDrop::new(rvec![3, 5, 8]);

// safety: `mdrop` is never accessed again
let moveptr = unsafe { MovePtr::from_raw(manuallydrop_as_raw_mut(&mut mdrop)) };
assert_eq!(moveptr[..], [3, 5, 8]);

let vector: RVec<u8> = MovePtr::into_inner(moveptr);
assert_eq!(vector[..], [3, 5, 8]);

pub const fn as_ptr(this: &Self) -> *const T

Gets a raw pointer to the value being moved.

Example

use abi_stable::{
    pointer_trait::OwnedPointer, sabi_types::MovePtr, std_types::RBox,
};

let rbox = RBox::new(String::from("NOPE"));
let address_rbox = &*rbox as *const String as usize;

rbox.in_move_ptr(|move_ptr| {
    assert_eq!(address_rbox, MovePtr::as_ptr(&move_ptr) as usize);
});

pub fn as_mut_ptr(this: &mut Self) -> *mut T

Gets a raw pointer to the value being moved.

Example

Example

use abi_stable::{
    pointer_trait::OwnedPointer, sabi_types::MovePtr, std_types::RBox,
};

let rbox = RBox::new(String::from("NOPE"));
let address_rbox = &*rbox as *const String as usize;

rbox.in_move_ptr(|mut move_ptr| {
    assert_eq!(address_rbox, MovePtr::as_mut_ptr(&mut move_ptr) as usize);
});

pub const fn into_raw(this: Self) -> *mut T

Converts this MovePtr into a raw pointer, which must be moved from before the pointed to value is deallocated, otherwise the value will be leaked.

Example

use abi_stable::{
    pointer_trait::OwnedPointer, sabi_types::MovePtr, std_types::RBox,
};

let rbox = RBox::new(String::from("NOPE"));

let string =
    rbox.in_move_ptr(|move_ptr| unsafe { MovePtr::into_raw(move_ptr).read() });

assert_eq!(string, String::from("NOPE"));

pub fn into_box(this: Self) -> Box<T>

Moves the value into a new Box<T>

Example

use abi_stable::{
    pointer_trait::OwnedPointer, sabi_types::MovePtr, std_types::RBox,
};

let rbox = RBox::new(String::from("WHAT!!!"));

let boxed = rbox.in_move_ptr(|move_ptr| unsafe { MovePtr::into_box(move_ptr) });

assert_eq!(boxed, Box::new(String::from("WHAT!!!")));

pub fn into_rbox(this: Self) -> RBox<T>

Moves the value into a new RBox<T>

Example

use abi_stable::{
    pointer_trait::OwnedPointer, sabi_types::MovePtr, std_types::RBox,
};

let rbox = RBox::new(String::from("WHAT!!!"));

let boxed = rbox.in_move_ptr(|move_ptr| unsafe { MovePtr::into_rbox(move_ptr) });

assert_eq!(boxed, RBox::new(String::from("WHAT!!!")));

pub fn into_inner(this: Self) -> T

Moves the value out of the reference

Example

use abi_stable::{
    pointer_trait::OwnedPointer, sabi_types::MovePtr, std_types::RBox,
};

let rbox = RBox::new(String::from("(The Wi)zard(of)oz"));

let string = rbox.in_move_ptr(|ptr| MovePtr::into_inner(ptr));

assert_eq!(string, String::from("(The Wi)zard(of)oz"));

pub const unsafe fn transmute<U>(this: Self) -> MovePtr<'a, U>

where U: 'a,

Transmute this RMove<'a, T> into a RMove<'a, U>.

Safety

This has the safety requirements as std::mem::transmute, as well as requiring that this MovePtr is aligned for U.

Example

use abi_stable::{
    pointer_trait::OwnedPointer,
    sabi_types::MovePtr,
    std_types::{RBox, RString, RVec},
};

let rbox = RBox::new(RString::from("hello"));

let bytes = rbox.in_move_ptr(|ptr| unsafe {
    MovePtr::into_inner(MovePtr::transmute::<RVec<u8>>(ptr))
});

assert_eq!(bytes.as_slice(), b"hello");

Trait Implementations

impl<'a, T> Debug for MovePtr<'a, T>

where T: Debug,

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

Formats the value using the given formatter.

impl<'a, T> Deref for MovePtr<'a, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'a, T> DerefMut for MovePtr<'a, T>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<'a, T> Display for MovePtr<'a, T>

where T: Display,

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

Formats the value using the given formatter.

impl<'a, T> Drop for MovePtr<'a, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T> GetStaticEquivalent_ for MovePtr<'a, T>

where T: __StableAbi + 'a,

type StaticEquivalent = _static_MovePtr<'static, <T as GetStaticEquivalent_>::StaticEquivalent>

The 'static equivalent of Self

impl<'a, T> Hash for MovePtr<'a, T>

where T: Hash,

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

where H: Hasher,

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<'a, T> IntoInner for MovePtr<'a, T>

type Element = T

The type of the value this owns.

fn into_inner_(self) -> T

Unwraps this type into its owned value.

impl<'a, T> Ord for MovePtr<'a, 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 + PartialOrd,

Restrict a value to a certain interval.

impl<'a, T> PartialEq for MovePtr<'a, T>

where T: PartialEq,

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, T> PartialOrd for MovePtr<'a, T>

where T: PartialOrd,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a, T> StableAbi for MovePtr<'a, T>

where T: __StableAbi + 'a,

type IsNonZeroType = <NonNull<T> as StableAbi>::IsNonZeroType

Whether this type has a single invalid bit-pattern.

const LAYOUT: &'static TypeLayout = _

The layout of the type provided by implementors.

const ABI_CONSTS: AbiConsts = _

const-equivalents of the associated types.

impl<'a, T> Eq for MovePtr<'a, T>

where T: Eq,

impl<'a, T: Send> Send for MovePtr<'a, T>

impl<'a, T: Sync> Sync for MovePtr<'a, T>