Trait ForeignOwnable

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

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

    // Provided method
    unsafe fn try_from_foreign(ptr: *const 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.

Required Associated Types

type Borrowed<'a>

Type of values borrowed between calls to ForeignOwnable::into_foreign and ForeignOwnable::from_foreign.

Required Methods

fn into_foreign(self) -> *const c_void

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

The foreign representation is a pointer to void. There are no guarantees for this pointer. For example, it might be invalid, dangling or pointing 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 borrow<'a>(ptr: *const c_void) -> Self::Borrowed<'a>

Borrows a foreign-owned object.

Safety

ptr must have been returned by a previous call to ForeignOwnable::into_foreign for which a previous matching ForeignOwnable::from_foreign hasn’t been called yet.

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

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

Safety

ptr must have been returned by a previous call to ForeignOwnable::into_foreign for which a previous matching ForeignOwnable::from_foreign hasn’t been called yet. Additionally, all instances (if any) of values returned by ForeignOwnable::borrow for this object must have been dropped.

Provided Methods

unsafe fn try_from_foreign(ptr: *const 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 ForeignOwnable::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 Borrowed<'a> = ()

fn into_foreign(self) -> *const c_void

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

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

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

where A: Allocator,

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

fn into_foreign(self) -> *const c_void

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

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

Implementors

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

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

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

where A: Allocator,

type Borrowed<'a> = &'a T