mirror of
https://github.com/torvalds/linux
synced 2024-09-06 09:51:23 +00:00
rust: types: introduce ForeignOwnable
It was originally called `PointerWrapper`. It is used to convert a Rust object to a pointer representation (void *) that can be stored on the C side, used, and eventually returned to Rust. Signed-off-by: Wedson Almeida Filho <wedsonaf@gmail.com> Reviewed-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com> Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com> Reviewed-by: Gary Guo <gary@garyguo.net> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
This commit is contained in:
parent
4d4692a2ff
commit
0fc4424d24
|
@ -16,6 +16,7 @@
|
|||
#![feature(coerce_unsized)]
|
||||
#![feature(core_ffi_c)]
|
||||
#![feature(dispatch_from_dyn)]
|
||||
#![feature(generic_associated_types)]
|
||||
#![feature(receiver_trait)]
|
||||
#![feature(unsize)]
|
||||
|
||||
|
|
|
@ -8,6 +8,60 @@
|
|||
ops::{Deref, DerefMut},
|
||||
};
|
||||
|
||||
/// 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.
|
||||
pub trait ForeignOwnable: Sized {
|
||||
/// Type of values borrowed between calls to [`ForeignOwnable::into_foreign`] and
|
||||
/// [`ForeignOwnable::from_foreign`].
|
||||
type Borrowed<'a>;
|
||||
|
||||
/// Converts a Rust-owned object to a foreign-owned one.
|
||||
///
|
||||
/// The foreign representation is a pointer to void.
|
||||
fn into_foreign(self) -> *const core::ffi::c_void;
|
||||
|
||||
/// 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.
|
||||
/// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow_mut`]
|
||||
/// for this object must have been dropped.
|
||||
unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
|
||||
|
||||
/// Mutably 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.
|
||||
/// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] and
|
||||
/// [`ForeignOwnable::borrow_mut`] for this object must have been dropped.
|
||||
unsafe fn borrow_mut(ptr: *const core::ffi::c_void) -> ScopeGuard<Self, fn(Self)> {
|
||||
// SAFETY: The safety requirements ensure that `ptr` came from a previous call to
|
||||
// `into_foreign`.
|
||||
ScopeGuard::new_with_data(unsafe { Self::from_foreign(ptr) }, |d| {
|
||||
d.into_foreign();
|
||||
})
|
||||
}
|
||||
|
||||
/// 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`] and
|
||||
/// [`ForeignOwnable::borrow_mut`] for this object must have been dropped.
|
||||
unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
|
||||
}
|
||||
|
||||
/// Runs a cleanup function/closure when dropped.
|
||||
///
|
||||
/// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running.
|
||||
|
|
Loading…
Reference in a new issue