Trait ForeignOwnable

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

    const FOREIGN_ALIGN: usize;

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

    // Provided method
    unsafe fn try_from_foreign(ptr: *mut c_void) -> 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

• Implementations must satisfy the guarantees of Self::into_foreign.

Required Associated Constants

const FOREIGN_ALIGN: usize

The alignment of pointers returned by into_foreign.

Required Associated Types

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 c_void

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

The foreign representation is a pointer to void. Aside from the guarantees listed below, there are no other guarantees for this pointer. For example, it might be invalid, dangling or pointing to uninitialized memory. Using it in any way except for from_foreign, try_from_foreign, borrow, or borrow_mut can result in undefined behavior.

Guarantees

• Minimum alignment of returned pointer is Self::FOREIGN_ALIGN.
• The returned pointer is not null.

unsafe fn from_foreign(ptr: *mut c_void) -> 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 c_void) -> 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 c_void) -> 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 c_void) -> 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 ()

const FOREIGN_ALIGN: usize = 1usize

type Borrowed<'a> = ()

type BorrowedMut<'a> = ()

fn into_foreign(self) -> *mut c_void

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

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

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

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

where A: Allocator,

const FOREIGN_ALIGN: usize

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

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

fn into_foreign(self) -> *mut c_void

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

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

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

Implementors

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

const FOREIGN_ALIGN: usize

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,

const FOREIGN_ALIGN: usize

type Borrowed<'a> = &'a T

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