[v2,2/5] rust: types: introduce `ForeignOwnable`
Commit Message
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>
---
v1 -> v2: Use `Self` instead of generic type in `borrow_mut`
rust/kernel/lib.rs | 1 +
rust/kernel/types.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 55 insertions(+)
Comments
On Mon, 30 Jan 2023 03:44:01 -0300
Wedson Almeida Filho <wedsonaf@gmail.com> wrote:
> 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>
> ---
> v1 -> v2: Use `Self` instead of generic type in `borrow_mut`
>
> rust/kernel/lib.rs | 1 +
> rust/kernel/types.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 55 insertions(+)
>
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index e0b0e953907d..223564f9f0cc 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -16,6 +16,7 @@
> #![feature(coerce_unsized)]
> #![feature(core_ffi_c)]
> #![feature(dispatch_from_dyn)]
> +#![feature(generic_associated_types)]
> #![feature(receiver_trait)]
> #![feature(unsize)]
>
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index dd834bfcb57b..72710b7442a3 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -8,6 +8,60 @@ use core::{
> 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.
Wedson Almeida Filho <wedsonaf@gmail.com> writes:
> 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: Andreas Hindborg <a.hindborg@samsung.com>
It would be cool to see a debug implementation of this trait that verify
safety properties by using a counter at runtime. Panic if borrow_mut()
is called while there are live references in existence returned by
borrow().
> v1 -> v2: Use `Self` instead of generic type in `borrow_mut`
>
> rust/kernel/lib.rs | 1 +
> rust/kernel/types.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 55 insertions(+)
>
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index e0b0e953907d..223564f9f0cc 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -16,6 +16,7 @@
> #![feature(coerce_unsized)]
> #![feature(core_ffi_c)]
> #![feature(dispatch_from_dyn)]
> +#![feature(generic_associated_types)]
> #![feature(receiver_trait)]
> #![feature(unsize)]
>
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index dd834bfcb57b..72710b7442a3 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -8,6 +8,60 @@ use core::{
> 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.
@@ -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 @@ use core::{
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.