Skip to contentSkip to conversation

rust: types: Add `try_from_foreign()` method

PATCH Superseded Obei Sideg 3 participants 6 messages Jan 24, 2024 – Jan 28, 2024 1 message not in the archive Rust

v3 of 6 Superseded Latest is v6 →

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): [email protected]

Obei Sideg

author
#1 lore raw

PATCH v3 1/1 rust: types: Add `try_from_foreign()` method

Currently ForeignOwnable::from_foreign() only works for non-null pointers for the existing impls (e.g. Box, Arc). It may create a few duplicate code like:

```rust
// `p` is a maybe null pointer
if p.is_null() {
  None
} else {
  Some(unsafe { T::from_foreign(p) })
}
```
---
 rust/kernel/types.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
rust/kernel/types.rs +20 -0
index fdb778e65d79..f27f007ca543 100644
@@ -46,6 +46,26 @@ pub trait ForeignOwnable: Sized {
     /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] for
     /// this object must have been dropped.
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
+
+    /// Tries to convert a foreign-owned object back to a Rust-owned one.
+    ///
+    /// A convenience wrapper over [`from_foreign`] that returns [`None`] if `ptr` is null.
+    ///
+    /// # 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.
+    unsafe fn try_from_foreign(ptr: *const core::ffi::c_void) -> Option<Self> {
+        if ptr.is_null() {
+            None
+        } else {
+            // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
+            // call to `Self::into_foreign`.
+            unsafe { Some(Self::from_foreign(ptr)) }
+        }
+    }
 }
 
 impl<T: 'static> ForeignOwnable for Box<T> {
Signature · 1 line
2.39.2
reviewer
#2 lore raw

rust/kernel/types.rs pub trait ForeignOwnable: Sized { · line 59

Quoted 6 lines · Obei Sideg
rust/kernel/types.rs +6 -0
+    /// # 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.

The safety comment should say something along the lines of "If ptr is not null, then ...".

This was mentioned on v1 and v2 as well. Before you send another version, please either make this change or explain why you don't think it is appropriate.

Alice

author
#3 lore raw

I will change it to: ptr must either be null or satisfy the safety requirements for [from_foreign].

reviewer Reviewed-by
#4 lore raw
Quoted 3 lines · Obei Sideg

I will change it to: ptr must either be null or satisfy the safety requirements for [from_foreign].

Okay, thanks. With that change, you may add

Alice

author
#5 lore raw

PATCH v4 1/1 rust: types: Add `try_from_foreign()` method

In reply to Alice Ryhl

Currently ForeignOwnable::from_foreign() only works for non-null pointers for the existing impls (e.g. Box, Arc). It may create a few duplicate code like:

```rust
// `p` is a maybe null pointer
if p.is_null() {
  None
} else {
  unsafe { Some(Self::from_foreign(ptr)) }
}
```

Adding a try_from_foreign() method that will return null if ptr is null, otherwsie return from_foreign(ptr).

---
 rust/kernel/types.rs | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
rust/kernel/types.rs +17 -0
index fdb778e65d79..04a356ec3534 100644
@@ -46,6 +46,23 @@ pub trait ForeignOwnable: Sized {
     /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] for
     /// this object must have been dropped.
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
+
+    /// Tries to convert a foreign-owned object back to a Rust-owned one.
+    ///
+    /// A convenience wrapper over [`from_foreign`] that returns [`None`] if `ptr` is null.
+    ///
+    /// # Safety
+    ///
+    /// `ptr` must either be null or satisfy the safety requirements for [`from_foreign`].
+    unsafe fn try_from_foreign(ptr: *const core::ffi::c_void) -> Option<Self> {
+        if ptr.is_null() {
+            None
+        } else {
+            // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
+            // call to [`into_foreign`].
+            unsafe { Some(Self::from_foreign(ptr)) }
+        }
+    }
 }
 
 impl<T: 'static> ForeignOwnable for Box<T> {
Signature · 1 line
2.39.2
#6 lore raw
In reply to Obei Sideg
Quoted 4 lines · Obei Sideg

Currently ForeignOwnable::from_foreign() only works for non-null pointers for the existing impls (e.g. Box, Arc). It may create a few duplicate code like:

Quoted 8 lines
```rust
// `p` is a maybe null pointer
if p.is_null() {
  None
} else {
  Some(unsafe { T::from_foreign(p) })
}
```

In the commit log, you explain the current status, which is good for explaining "why the patch is needed", however, you should also add a few sentenses explaining how your patch would help/improve the current situation, otherwise it looks like an unfinished sentense to me.

Thanks!

Regards,
Boqun

Quoted 42 lines
---
 rust/kernel/types.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
rust/kernel/types.rs +20 -0
index fdb778e65d79..f27f007ca543 100644
@@ -46,6 +46,26 @@ pub trait ForeignOwnable: Sized {
     /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] for
     /// this object must have been dropped.
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
+
+    /// Tries to convert a foreign-owned object back to a Rust-owned one.
+    ///
+    /// A convenience wrapper over [`from_foreign`] that returns [`None`] if `ptr` is null.
+    ///
+    /// # 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.
+    unsafe fn try_from_foreign(ptr: *const core::ffi::c_void) -> Option<Self> {
+        if ptr.is_null() {
+            None
+        } else {
+            // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
+            // call to `Self::into_foreign`.
+            unsafe { Some(Self::from_foreign(ptr)) }
+        }
+    }
 }
 
 impl<T: 'static> ForeignOwnable for Box<T> {
Signature · 1 line
2.39.2