Trait ForeignOwnable

pub unsafe trait ForeignOwnable: Sized {
    type PointedTo;
    type Borrowed<'a>;
    type BorrowedMut<'a>;

    // Required methods
    fn into_foreign(self) -> *mut Self::PointedTo;
    unsafe fn from_foreign(ptr: *mut Self::PointedTo) -> Self;
    unsafe fn borrow<'a>(ptr: *mut Self::PointedTo) -> Self::Borrowed<'a>;
    unsafe fn borrow_mut<'a>(ptr: *mut Self::PointedTo) -> Self::BorrowedMut<'a>;

    // Provided method
    unsafe fn try_from_foreign(ptr: *mut Self::PointedTo) -> Option<Self> { ... }
}

Used to transfer ownership to and from foreign (non-Rust) languages.

Ownership is transferred from Rust to a foreign language by calling Self::into_foreign and later may be transferred back to Rust by calling Self::from_foreign.

This trait is meant to be used in cases when Rust objects are stored in C objects and eventually “freed” back to Rust.

Safety

Implementers must ensure that into_foreign returns a pointer which meets the alignment requirements of PointedTo.

Required Associated Types

type PointedTo

Type used when the value is foreign-owned. In practical terms only defines the alignment of the pointer.

type Borrowed<'a>

Type used to immutably borrow a value that is currently foreign-owned.

type BorrowedMut<'a>

Type used to mutably borrow a value that is currently foreign-owned.

Required Methods

fn into_foreign(self) -> *mut Self::PointedTo

Converts a Rust-owned object to a foreign-owned one.

Guarantees

The return value is guaranteed to be well-aligned, but there are no other guarantees for this pointer. For example, it might be null, dangling, or point to uninitialized memory. Using it in any way except for ForeignOwnable::from_foreign, ForeignOwnable::borrow, ForeignOwnable::try_from_foreign can result in undefined behavior.

unsafe fn from_foreign(ptr: *mut Self::PointedTo) -> Self

Converts a foreign-owned object back to a Rust-owned one.

Safety

The provided pointer must have been returned by a previous call to into_foreign, and it must not be passed to from_foreign more than once.

unsafe fn borrow<'a>(ptr: *mut Self::PointedTo) -> Self::Borrowed<'a>

Borrows a foreign-owned object immutably.

This method provides a way to access a foreign-owned value from Rust immutably. It provides you with exactly the same abilities as an &Self when the value is Rust-owned.

Safety

The provided pointer must have been returned by a previous call to into_foreign, and if the pointer is ever passed to from_foreign, then that call must happen after the end of the lifetime 'a.

unsafe fn borrow_mut<'a>(ptr: *mut Self::PointedTo) -> Self::BorrowedMut<'a>

Borrows a foreign-owned object mutably.

This method provides a way to access a foreign-owned value from Rust mutably. It provides you with exactly the same abilities as an &mut Self when the value is Rust-owned, except that the address of the object must not be changed.

Note that for types like Arc, an &mut Arc<T> only gives you immutable access to the inner value, so this method also only provides immutable access in that case.

In the case of Box<T>, this method gives you the ability to modify the inner T, but it does not let you change the box itself. That is, you cannot change which allocation the box points at.

Safety

The provided pointer must have been returned by a previous call to into_foreign, and if the pointer is ever passed to from_foreign, then that call must happen after the end of the lifetime 'a.

The lifetime 'a must not overlap with the lifetime of any other call to borrow or borrow_mut on the same object.

Provided Methods

unsafe fn try_from_foreign(ptr: *mut Self::PointedTo) -> Option<Self>

Tries to convert a foreign-owned object back to a Rust-owned one.

A convenience wrapper over ForeignOwnable::from_foreign that returns None if ptr is null.

Safety

ptr must either be null or satisfy the safety requirements for from_foreign.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl ForeignOwnable for ()

type PointedTo = ()

type Borrowed<'a> = ()

type BorrowedMut<'a> = ()

fn into_foreign(self) -> *mut Self::PointedTo

unsafe fn from_foreign(_: *mut Self::PointedTo) -> Self

unsafe fn borrow<'a>(_: *mut Self::PointedTo) -> Self::Borrowed<'a>

unsafe fn borrow_mut<'a>(_: *mut Self::PointedTo) -> Self::BorrowedMut<'a>

impl<T: 'static, A> ForeignOwnable for Pin<Box<T, A>>

where A: Allocator,

type PointedTo = T

type Borrowed<'a> = Pin<&'a T>

type BorrowedMut<'a> = Pin<&'a mut T>

fn into_foreign(self) -> *mut Self::PointedTo

unsafe fn from_foreign(ptr: *mut Self::PointedTo) -> Self

unsafe fn borrow<'a>(ptr: *mut Self::PointedTo) -> Pin<&'a T>

unsafe fn borrow_mut<'a>(ptr: *mut Self::PointedTo) -> Pin<&'a mut T>

Implementors

impl<T: 'static> ForeignOwnable for Arc<T>

type PointedTo = ArcInner<T>

type Borrowed<'a> = ArcBorrow<'a, T>

type BorrowedMut<'a> = <Arc<T> as ForeignOwnable>::Borrowed<'a>

impl<T: 'static, A> ForeignOwnable for Box<T, A>

where A: Allocator,

type PointedTo = T

type Borrowed<'a> = &'a T

type BorrowedMut<'a> = &'a mut T