pub trait ForeignOwnable: Sized {
type Borrowed<'a>;
type BorrowedMut<'a>;
// 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> { ... }
}Expand description
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§
Sourcetype BorrowedMut<'a>
type BorrowedMut<'a>
Type used to mutably borrow a value that is currently foreign-owned.
Required Methods§
Sourcefn into_foreign(self) -> *mut c_void
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. 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 from_foreign, try_from_foreign, borrow, or borrow_mut can
result in undefined behavior.
Sourceunsafe fn from_foreign(ptr: *mut c_void) -> Self
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.
Sourceunsafe fn borrow<'a>(ptr: *mut c_void) -> Self::Borrowed<'a>
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.
Sourceunsafe fn borrow_mut<'a>(ptr: *mut c_void) -> Self::BorrowedMut<'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§
Sourceunsafe fn try_from_foreign(ptr: *mut c_void) -> Option<Self>
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.