Skip to contentSkip to conversation

rust: add improved version of `ForeignOwnable::borrow_mut`

PATCH In review Alice Ryhl 6 participants 13 messages Jul 10, 2023 – Oct 25, 2023

Subsystems (2)
lore
Share & tools
lore

Alice Ryhl

author maintainer
#0 lore raw

PATCH 1/1 rust: add improved version of `ForeignOwnable::borrow_mut`

Previously, the ForeignOwnable trait had a method called borrow_mut that was intended to provide mutable access to the inner value. However, the method accidentally made it possible to change the address of the object being modified, which usually isn't what we want. (And when we want that, it can be done by calling from_foreign and into_foreign, like how the old borrow_mut was implemented.)

In this patch, we introduce an alternate definition of borrow_mut that solves the previous problem. Conceptually, given a pointer type P that implements ForeignOwnable, the borrow_mut method gives you the same kind of access as an &mut P would, except that it does not let you change the pointer P itself.

This is analogous to how the existing borrow method provides the same kind of access to the inner value as an &P.

Note that for types like Arc, having an &mut Arc<T> only gives you immutable access to the inner T. This is because mutable references assume exclusive access, but there might be other handles to the same reference counted value, so the access isn't exclusive. The Arc type implements this by making borrow_mut return the same type as borrow.

---

This patch depends on https://lore.kernel.org/all/[email protected]/

 rust/kernel/sync/arc.rs | 31 +++++++++-----
 rust/kernel/types.rs    | 93 ++++++++++++++++++++++++++++++-----------
 2 files changed, 89 insertions(+), 35 deletions(-)
rust/kernel/types.rs +69 -24
index d479f8da8f38..1c2fb36906b6 100644
@@ -20,66 +20,111 @@
 /// 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 used to immutably borrow a value that is currently foreign-owned.
     type Borrowed<'a>;
 
+    /// Type used to mutably borrow a value that is currently foreign-owned.
+    type BorrowedMut<'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.
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
-
     /// 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.
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
+
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
+    /// [`from_foreign`]: Self::from_foreign
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'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 this method does not let you swap the foreign-owned object for another. (That is, it
+    /// does not let you change the address of the void pointer that the foreign code is storing.)
+    ///
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
+    /// [`from_foreign`]: Self::from_foreign
+    /// [`borrow`]: Self::borrow
+    /// [`Arc`]: crate::sync::Arc
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> Self::BorrowedMut<'a>;
 }
 
 impl<T: 'static> ForeignOwnable for Box<T> {
     type Borrowed<'a> = &'a T;
+    type BorrowedMut<'a> = &'a mut T;
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         Box::into_raw(self) as _
     }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
-        // SAFETY: The safety requirements for this function ensure that the object is still alive,
-        // so it is safe to dereference the raw pointer.
-        // The safety requirements of `from_foreign` also ensure that the object remains alive for
-        // the lifetime of the returned value.
-        unsafe { &*ptr.cast() }
-    }
-
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
         // call to `Self::into_foreign`.
         unsafe { Box::from_raw(ptr as _) }
     }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
+        // SAFETY: The safety requirements of this method ensure that the object remains alive and
+        // immutable for the duration of 'a.
+        unsafe { &*ptr.cast() }
+    }
+
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> &'a mut T {
+        // SAFETY: The safety requirements of this method ensure that the pointer is valid and that
+        // nothing else will access the value for the duration of 'a.
+        unsafe { &mut *ptr.cast_mut().cast() }
+    }
 }
 
 impl ForeignOwnable for () {
     type Borrowed<'a> = ();
+    type BorrowedMut<'a> = ();
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         core::ptr::NonNull::dangling().as_ptr()
     }
 
-    unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
-
     unsafe fn from_foreign(_: *const core::ffi::c_void) -> Self {}
+
+    unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
+    unsafe fn borrow_mut<'a>(_: *const core::ffi::c_void) -> Self::BorrowedMut<'a> {}
 }
 
 /// Runs a cleanup function/closure when dropped.
rust/kernel/sync/arc.rs +20 -11
index 172f563976a9..f152a562c9c3 100644
@@ -232,26 +232,35 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
 impl<T: 'static> ForeignOwnable for Arc<T> {
     type Borrowed<'a> = ArcBorrow<'a, T>;
+    // Mutable access to the `Arc` does not give any extra abilities over
+    // immutable access.
+    type BorrowedMut<'a> = ArcBorrow<'a, T>;
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         ManuallyDrop::new(self).ptr.as_ptr() as _
     }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
-        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
-        // a previous call to `Arc::into_foreign`.
-        let inner = NonNull::new(ptr as *mut ArcInner<T>).unwrap();
-
-        // SAFETY: The safety requirements of `from_foreign` ensure that the object remains alive
-        // for the lifetime of the returned value.
-        unsafe { ArcBorrow::new(inner) }
-    }
-
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
         // SAFETY: By the safety requirement of this function, we know that `ptr` came from
         // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and
         // holds a reference count increment that is transferrable to us.
-        unsafe { Self::from_inner(NonNull::new(ptr as _).unwrap()) }
+        unsafe { Self::from_inner(NonNull::new_unchecked(ptr as _)) }
     }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
+        // a previous call to `Arc::into_foreign`.
+        let inner = unsafe { NonNull::new_unchecked(ptr as *mut ArcInner<T>) };
+
+        // SAFETY: The safety requirements ensure that we will not give up our
+        // foreign-owned refcount while the `ArcBorrow` is still live.
+        unsafe { ArcBorrow::new(inner) }
+    }
+
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: The safety requirements for `borrow_mut` are a superset of the safety
+        // requirements for `borrow`.
+        unsafe { Self::borrow(ptr) }
+    }
 }
 

base-commit: d2e3115d717197cb2bc020dd1f06b06538474ac3
prerequisite-patch-id: b493b9015cb19f599c4bc03127733193b11ca822

Signature · 1 line
2.41.0.255.g8b1d071c50-goog
Reviewed-by on v1 1/1
#1 lore raw
Quoted 37 lines · Alice Ryhl

Previously, the ForeignOwnable trait had a method called borrow_mut that was intended to provide mutable access to the inner value. However, the method accidentally made it possible to change the address of the object being modified, which usually isn't what we want. (And when we want that, it can be done by calling from_foreign and into_foreign, like how the old borrow_mut was implemented.)

In this patch, we introduce an alternate definition of borrow_mut that solves the previous problem. Conceptually, given a pointer type P that implements ForeignOwnable, the borrow_mut method gives you the same kind of access as an &mut P would, except that it does not let you change the pointer P itself.

This is analogous to how the existing borrow method provides the same kind of access to the inner value as an &P.

Note that for types like Arc, having an &mut Arc<T> only gives you immutable access to the inner T. This is because mutable references assume exclusive access, but there might be other handles to the same reference counted value, so the access isn't exclusive. The Arc type implements this by making borrow_mut return the same type as borrow.

---

This patch depends on https://lore.kernel.org/all/[email protected]/

 rust/kernel/sync/arc.rs | 31 +++++++++-----
 rust/kernel/types.rs    | 93 ++++++++++++++++++++++++++++++-----------
 2 files changed, 89 insertions(+), 35 deletions(-)
rust/kernel/types.rs +0 -0
index d479f8da8f38..1c2fb36906b6 100644
@@ -20,66 +20,111 @@
 /// This trait is meant to be used in cases when Rust objects are stored in C objects and

rust/kernel/types.rs line 28

Quoted 10 lines
rust/kernel/types.rs +4 -2
 /// eventually "freed" back to Rust.
 pub trait ForeignOwnable: Sized {
-    /// Type of values borrowed between calls to [`ForeignOwnable::into_foreign`] and
-    /// [`ForeignOwnable::from_foreign`].
+    /// Type used to immutably borrow a value that is currently foreign-owned.
     type Borrowed<'a>;
 
+    /// Type used to mutably borrow a value that is currently foreign-owned.
+    type BorrowedMut<'a>;
+

I would probably want to say "if the impl ForeignOwnable doesn't have the exclusive ownership, BorrowedMut should be the same as Borrowed" for logical self-consistent, and even further make it as default as follow:

	type BorrowedMut<'a> = Self::Borrowed<'a>;

	unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> Self::BorrowedMut<'a> {
	    Self::borrow(ptr)
	}

but it might be over-engineering (and require associated_type_defaults and more)...

Anyway,

Regards,
Boqun

Quoted 181 lines
rust/kernel/types.rs +65 -22
     /// 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.
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
-
     /// 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.
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
+
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
+    /// [`from_foreign`]: Self::from_foreign
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'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 this method does not let you swap the foreign-owned object for another. (That is, it
+    /// does not let you change the address of the void pointer that the foreign code is storing.)
+    ///
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
+    /// [`from_foreign`]: Self::from_foreign
+    /// [`borrow`]: Self::borrow
+    /// [`Arc`]: crate::sync::Arc
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> Self::BorrowedMut<'a>;
 }
 
 impl<T: 'static> ForeignOwnable for Box<T> {
     type Borrowed<'a> = &'a T;
+    type BorrowedMut<'a> = &'a mut T;
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         Box::into_raw(self) as _
     }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
-        // SAFETY: The safety requirements for this function ensure that the object is still alive,
-        // so it is safe to dereference the raw pointer.
-        // The safety requirements of `from_foreign` also ensure that the object remains alive for
-        // the lifetime of the returned value.
-        unsafe { &*ptr.cast() }
-    }
-
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
         // call to `Self::into_foreign`.
         unsafe { Box::from_raw(ptr as _) }
     }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
+        // SAFETY: The safety requirements of this method ensure that the object remains alive and
+        // immutable for the duration of 'a.
+        unsafe { &*ptr.cast() }
+    }
+
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> &'a mut T {
+        // SAFETY: The safety requirements of this method ensure that the pointer is valid and that
+        // nothing else will access the value for the duration of 'a.
+        unsafe { &mut *ptr.cast_mut().cast() }
+    }
 }
 
 impl ForeignOwnable for () {
     type Borrowed<'a> = ();
+    type BorrowedMut<'a> = ();
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         core::ptr::NonNull::dangling().as_ptr()
     }
 
-    unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
-
     unsafe fn from_foreign(_: *const core::ffi::c_void) -> Self {}
+
+    unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
+    unsafe fn borrow_mut<'a>(_: *const core::ffi::c_void) -> Self::BorrowedMut<'a> {}
 }
 
 /// Runs a cleanup function/closure when dropped.
rust/kernel/sync/arc.rs +20 -11
index 172f563976a9..f152a562c9c3 100644
@@ -232,26 +232,35 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
 impl<T: 'static> ForeignOwnable for Arc<T> {
     type Borrowed<'a> = ArcBorrow<'a, T>;
+    // Mutable access to the `Arc` does not give any extra abilities over
+    // immutable access.
+    type BorrowedMut<'a> = ArcBorrow<'a, T>;
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         ManuallyDrop::new(self).ptr.as_ptr() as _
     }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
-        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
-        // a previous call to `Arc::into_foreign`.
-        let inner = NonNull::new(ptr as *mut ArcInner<T>).unwrap();
-
-        // SAFETY: The safety requirements of `from_foreign` ensure that the object remains alive
-        // for the lifetime of the returned value.
-        unsafe { ArcBorrow::new(inner) }
-    }
-
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
         // SAFETY: By the safety requirement of this function, we know that `ptr` came from
         // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and
         // holds a reference count increment that is transferrable to us.
-        unsafe { Self::from_inner(NonNull::new(ptr as _).unwrap()) }
+        unsafe { Self::from_inner(NonNull::new_unchecked(ptr as _)) }
     }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
+        // a previous call to `Arc::into_foreign`.
+        let inner = unsafe { NonNull::new_unchecked(ptr as *mut ArcInner<T>) };
+
+        // SAFETY: The safety requirements ensure that we will not give up our
+        // foreign-owned refcount while the `ArcBorrow` is still live.
+        unsafe { ArcBorrow::new(inner) }
+    }
+
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: The safety requirements for `borrow_mut` are a superset of the safety
+        // requirements for `borrow`.
+        unsafe { Self::borrow(ptr) }
+    }
 }
 

base-commit: d2e3115d717197cb2bc020dd1f06b06538474ac3
prerequisite-patch-id: b493b9015cb19f599c4bc03127733193b11ca822

Signature · 1 line
2.41.0.255.g8b1d071c50-goog
author maintainer
#2 lore raw
Quoted 45 lines · Boqun Feng
Quoted 44 lines · Alice Ryhl

Previously, the ForeignOwnable trait had a method called borrow_mut that was intended to provide mutable access to the inner value. However, the method accidentally made it possible to change the address of the object being modified, which usually isn't what we want. (And when we want that, it can be done by calling from_foreign and into_foreign, like how the old borrow_mut was implemented.)

In this patch, we introduce an alternate definition of borrow_mut that solves the previous problem. Conceptually, given a pointer type P that implements ForeignOwnable, the borrow_mut method gives you the same kind of access as an &mut P would, except that it does not let you change the pointer P itself.

This is analogous to how the existing borrow method provides the same kind of access to the inner value as an &P.

Note that for types like Arc, having an &mut Arc<T> only gives you immutable access to the inner T. This is because mutable references assume exclusive access, but there might be other handles to the same reference counted value, so the access isn't exclusive. The Arc type implements this by making borrow_mut return the same type as borrow.

---

This patch depends on https://lore.kernel.org/all/[email protected]/

 rust/kernel/sync/arc.rs | 31 +++++++++-----
 rust/kernel/types.rs    | 93 ++++++++++++++++++++++++++++++-----------
 2 files changed, 89 insertions(+), 35 deletions(-)
rust/kernel/types.rs +1 -2
index d479f8da8f38..1c2fb36906b6 100644
@@ -20,66 +20,111 @@
 /// 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 used to immutably borrow a value that is currently foreign-owned.
     type Borrowed<'a>;
 
Quoted 7 lines

rust/kernel/types.rs line 28

Quoted 3 lines
rust/kernel/types.rs +3 -0
+    /// Type used to mutably borrow a value that is currently foreign-owned.
+    type BorrowedMut<'a>;
+

I would probably want to say "if the impl ForeignOwnable doesn't have the exclusive ownership, BorrowedMut should be the same as Borrowed" for logical self-consistent,

I don't phrase it as a requirement, but I do already say something along these lines.

Quoted 10 lines

and even further make it as default as follow:

	type BorrowedMut<'a> = Self::Borrowed<'a>;

	unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> Self::BorrowedMut<'a> {
	    Self::borrow(ptr)
	}

but it might be over-engineering (and require associated_type_defaults and more)...

I don't think it makes sense to use defaults here. There are very few implementers of this trait, and I'd like all of them to explicitly think about whether BorrowedMut should be the same as Borrowed, or different.

Quoted 6 lines

Anyway,

Regards,
Boqun

Alice

Reviewed-by on v1 1/1
#3 lore raw
In reply to Alice Ryhl
Quoted 22 lines · Alice Ryhl

Previously, the ForeignOwnable trait had a method called borrow_mut that was intended to provide mutable access to the inner value. However, the method accidentally made it possible to change the address of the object being modified, which usually isn't what we want. (And when we want that, it can be done by calling from_foreign and into_foreign, like how the old borrow_mut was implemented.)

In this patch, we introduce an alternate definition of borrow_mut that solves the previous problem. Conceptually, given a pointer type P that implements ForeignOwnable, the borrow_mut method gives you the same kind of access as an &mut P would, except that it does not let you change the pointer P itself.

This is analogous to how the existing borrow method provides the same kind of access to the inner value as an &P.

Note that for types like Arc, having an &mut Arc<T> only gives you immutable access to the inner T. This is because mutable references assume exclusive access, but there might be other handles to the same reference counted value, so the access isn't exclusive. The Arc type implements this by making borrow_mut return the same type as borrow.

Quoted 3 lines

---
[...]

Reviewed-by on v1 1/1
#4 lore raw
In reply to Alice Ryhl
Quoted 16 lines · Alice Ryhl

Previously, the ForeignOwnable trait had a method called borrow_mut that was intended to provide mutable access to the inner value. However, the method accidentally made it possible to change the address of the object being modified, which usually isn't what we want. (And when we want that, it can be done by calling from_foreign and into_foreign, like how the old borrow_mut was implemented.)

In this patch, we introduce an alternate definition of borrow_mut that solves the previous problem. Conceptually, given a pointer type P that implements ForeignOwnable, the borrow_mut method gives you the same kind of access as an &mut P would, except that it does not let you change the pointer P itself.

This is analogous to how the existing borrow method provides the same kind of access to the inner value as an &P.

Quoted 7 lines

Note that for types like Arc, having an &mut Arc<T> only gives you immutable access to the inner T. This is because mutable references assume exclusive access, but there might be other handles to the same reference counted value, so the access isn't exclusive. The Arc type implements this by making borrow_mut return the same type as borrow.

Signature · 2 lines
Cheers,
Benno
Quoted 205 lines

---

This patch depends on https://lore.kernel.org/all/[email protected]/

  rust/kernel/sync/arc.rs | 31 +++++++++-----
  rust/kernel/types.rs    | 93 ++++++++++++++++++++++++++++++-----------
  2 files changed, 89 insertions(+), 35 deletions(-)
rust/kernel/types.rs +69 -24
index d479f8da8f38..1c2fb36906b6 100644
@@ -20,66 +20,111 @@
  /// 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 used to immutably borrow a value that is currently foreign-owned.
      type Borrowed<'a>;
 
+    /// Type used to mutably borrow a value that is currently foreign-owned.
+    type BorrowedMut<'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.
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
-
      /// 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.
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
      unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
+
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
+    /// [`from_foreign`]: Self::from_foreign
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'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 this method does not let you swap the foreign-owned object for another. (That is, it
+    /// does not let you change the address of the void pointer that the foreign code is storing.)
+    ///
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
+    /// [`from_foreign`]: Self::from_foreign
+    /// [`borrow`]: Self::borrow
+    /// [`Arc`]: crate::sync::Arc
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> Self::BorrowedMut<'a>;
  }
 
  impl<T: 'static> ForeignOwnable for Box<T> {
      type Borrowed<'a> = &'a T;
+    type BorrowedMut<'a> = &'a mut T;
 
      fn into_foreign(self) -> *const core::ffi::c_void {
          Box::into_raw(self) as _
      }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
-        // SAFETY: The safety requirements for this function ensure that the object is still alive,
-        // so it is safe to dereference the raw pointer.
-        // The safety requirements of `from_foreign` also ensure that the object remains alive for
-        // the lifetime of the returned value.
-        unsafe { &*ptr.cast() }
-    }
-
      unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
          // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
          // call to `Self::into_foreign`.
          unsafe { Box::from_raw(ptr as _) }
      }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
+        // SAFETY: The safety requirements of this method ensure that the object remains alive and
+        // immutable for the duration of 'a.
+        unsafe { &*ptr.cast() }
+    }
+
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> &'a mut T {
+        // SAFETY: The safety requirements of this method ensure that the pointer is valid and that
+        // nothing else will access the value for the duration of 'a.
+        unsafe { &mut *ptr.cast_mut().cast() }
+    }
  }
 
  impl ForeignOwnable for () {
      type Borrowed<'a> = ();
+    type BorrowedMut<'a> = ();
 
      fn into_foreign(self) -> *const core::ffi::c_void {
          core::ptr::NonNull::dangling().as_ptr()
      }
 
-    unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
-
      unsafe fn from_foreign(_: *const core::ffi::c_void) -> Self {}
+
+    unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
+    unsafe fn borrow_mut<'a>(_: *const core::ffi::c_void) -> Self::BorrowedMut<'a> {}
  }
 
  /// Runs a cleanup function/closure when dropped.
rust/kernel/sync/arc.rs +20 -11
index 172f563976a9..f152a562c9c3 100644
@@ -232,26 +232,35 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
  impl<T: 'static> ForeignOwnable for Arc<T> {
      type Borrowed<'a> = ArcBorrow<'a, T>;
+    // Mutable access to the `Arc` does not give any extra abilities over
+    // immutable access.
+    type BorrowedMut<'a> = ArcBorrow<'a, T>;
 
      fn into_foreign(self) -> *const core::ffi::c_void {
          ManuallyDrop::new(self).ptr.as_ptr() as _
      }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
-        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
-        // a previous call to `Arc::into_foreign`.
-        let inner = NonNull::new(ptr as *mut ArcInner<T>).unwrap();
-
-        // SAFETY: The safety requirements of `from_foreign` ensure that the object remains alive
-        // for the lifetime of the returned value.
-        unsafe { ArcBorrow::new(inner) }
-    }
-
      unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
          // SAFETY: By the safety requirement of this function, we know that `ptr` came from
          // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and
          // holds a reference count increment that is transferrable to us.
-        unsafe { Self::from_inner(NonNull::new(ptr as _).unwrap()) }
+        unsafe { Self::from_inner(NonNull::new_unchecked(ptr as _)) }
      }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
+        // a previous call to `Arc::into_foreign`.
+        let inner = unsafe { NonNull::new_unchecked(ptr as *mut ArcInner<T>) };
+
+        // SAFETY: The safety requirements ensure that we will not give up our
+        // foreign-owned refcount while the `ArcBorrow` is still live.
+        unsafe { ArcBorrow::new(inner) }
+    }
+
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: The safety requirements for `borrow_mut` are a superset of the safety
+        // requirements for `borrow`.
+        unsafe { Self::borrow(ptr) }
+    }
  }
 

base-commit: d2e3115d717197cb2bc020dd1f06b06538474ac3
prerequisite-patch-id: b493b9015cb19f599c4bc03127733193b11ca822 --
2.41.0.255.g8b1d071c50-goog

#5 lore raw
In reply to Alice Ryhl
Quoted 85 lines · Alice Ryhl

Previously, the ForeignOwnable trait had a method called borrow_mut that was intended to provide mutable access to the inner value. However, the method accidentally made it possible to change the address of the object being modified, which usually isn't what we want. (And when we want that, it can be done by calling from_foreign and into_foreign, like how the old borrow_mut was implemented.)

In this patch, we introduce an alternate definition of borrow_mut that solves the previous problem. Conceptually, given a pointer type P that implements ForeignOwnable, the borrow_mut method gives you the same kind of access as an &mut P would, except that it does not let you change the pointer P itself.

This is analogous to how the existing borrow method provides the same kind of access to the inner value as an &P.

Note that for types like Arc, having an &mut Arc<T> only gives you immutable access to the inner T. This is because mutable references assume exclusive access, but there might be other handles to the same reference counted value, so the access isn't exclusive. The Arc type implements this by making borrow_mut return the same type as borrow.

---

This patch depends on https://lore.kernel.org/all/[email protected]/

 rust/kernel/sync/arc.rs | 31 +++++++++-----
 rust/kernel/types.rs    | 93 ++++++++++++++++++++++++++++++-----------
 2 files changed, 89 insertions(+), 35 deletions(-)
rust/kernel/types.rs +20 -14
index d479f8da8f38..1c2fb36906b6 100644
@@ -20,66 +20,111 @@
 /// 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 used to immutably borrow a value that is currently foreign-owned.
     type Borrowed<'a>;
 
+    /// Type used to mutably borrow a value that is currently foreign-owned.
+    type BorrowedMut<'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.
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
-
     /// 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.
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
+
+    /// 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.
+    ///

rust/kernel/types.rs line 64

Quoted 10 lines
rust/kernel/types.rs +10 -0
+    /// [`into_foreign`]: Self::into_foreign
+    /// [`from_foreign`]: Self::from_foreign
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'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 this method does not let you swap the foreign-owned object for another. (That is, it
+    /// does not let you change the address of the void pointer that the foreign code is storing.)

How about this:

"For a smart pointer P<T> this method provides mutable access to T if &mut P<T> would allow mutable access to T. Otherwise it provides immutable access to T."

The point is that the method provides access to the pointee, not the smart pointer itself. In fact it is perfectly fine to do a mem::swawp() for the pointee in the case of Box and depending on interpretation the sentence "does not let you swap the foreign-owned object for another" is confusing.

Quoted 116 lines
rust/kernel/types.rs +39 -10
+    ///
+    /// 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.
+    ///
+    /// [`into_foreign`]: Self::into_foreign
+    /// [`from_foreign`]: Self::from_foreign
+    /// [`borrow`]: Self::borrow
+    /// [`Arc`]: crate::sync::Arc
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> Self::BorrowedMut<'a>;
 }
 
 impl<T: 'static> ForeignOwnable for Box<T> {
     type Borrowed<'a> = &'a T;
+    type BorrowedMut<'a> = &'a mut T;
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         Box::into_raw(self) as _
     }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
-        // SAFETY: The safety requirements for this function ensure that the object is still alive,
-        // so it is safe to dereference the raw pointer.
-        // The safety requirements of `from_foreign` also ensure that the object remains alive for
-        // the lifetime of the returned value.
-        unsafe { &*ptr.cast() }
-    }
-
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
         // call to `Self::into_foreign`.
         unsafe { Box::from_raw(ptr as _) }
     }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
+        // SAFETY: The safety requirements of this method ensure that the object remains alive and
+        // immutable for the duration of 'a.
+        unsafe { &*ptr.cast() }
+    }
+
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> &'a mut T {
+        // SAFETY: The safety requirements of this method ensure that the pointer is valid and that
+        // nothing else will access the value for the duration of 'a.
+        unsafe { &mut *ptr.cast_mut().cast() }
+    }
 }
 
 impl ForeignOwnable for () {
     type Borrowed<'a> = ();
+    type BorrowedMut<'a> = ();
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         core::ptr::NonNull::dangling().as_ptr()
     }
 
-    unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
-
     unsafe fn from_foreign(_: *const core::ffi::c_void) -> Self {}
+
+    unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
+    unsafe fn borrow_mut<'a>(_: *const core::ffi::c_void) -> Self::BorrowedMut<'a> {}
 }
 
 /// Runs a cleanup function/closure when dropped.
rust/kernel/sync/arc.rs +10 -11
index 172f563976a9..f152a562c9c3 100644
@@ -232,26 +232,35 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
 impl<T: 'static> ForeignOwnable for Arc<T> {
     type Borrowed<'a> = ArcBorrow<'a, T>;
+    // Mutable access to the `Arc` does not give any extra abilities over
+    // immutable access.
+    type BorrowedMut<'a> = ArcBorrow<'a, T>;
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         ManuallyDrop::new(self).ptr.as_ptr() as _
     }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
-        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
-        // a previous call to `Arc::into_foreign`.
-        let inner = NonNull::new(ptr as *mut ArcInner<T>).unwrap();
-
-        // SAFETY: The safety requirements of `from_foreign` ensure that the object remains alive
-        // for the lifetime of the returned value.
-        unsafe { ArcBorrow::new(inner) }
-    }
-
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
         // SAFETY: By the safety requirement of this function, we know that `ptr` came from
         // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and
         // holds a reference count increment that is transferrable to us.
-        unsafe { Self::from_inner(NonNull::new(ptr as _).unwrap()) }
+        unsafe { Self::from_inner(NonNull::new_unchecked(ptr as _)) }
     }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
+        // a previous call to `Arc::into_foreign`.
+        let inner = unsafe { NonNull::new_unchecked(ptr as *mut ArcInner<T>) };
+

rust/kernel/sync/arc.rs pub fn ptr_eq(this: &Self, other: &Self) -> bool { · line 264

Quoted 10 lines
rust/kernel/sync/arc.rs +10 -0
+        // SAFETY: The safety requirements ensure that we will not give up our
+        // foreign-owned refcount while the `ArcBorrow` is still live.
+        unsafe { ArcBorrow::new(inner) }
+    }
+
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: The safety requirements for `borrow_mut` are a superset of the safety
+        // requirements for `borrow`.
+        unsafe { Self::borrow(ptr) }
+    }

I am not sure this makes sense. How about splitting the trait in two, immutable and mutable and only implementing the immutable one or Arc?

Best regards,
Andreas

author maintainer
#6 lore raw
Quoted 13 lines · Andreas Hindborg

rust/kernel/types.rs line 64

Quoted 6 lines
rust/kernel/types.rs +6 -0
+    /// 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 this method does not let you swap the foreign-owned object for another. (That is, it
+    /// does not let you change the address of the void pointer that the foreign code is storing.)

How about this:

"For a smart pointer P<T> this method provides mutable access to T if &mut P<T> would allow mutable access to T. Otherwise it provides immutable access to T."

Quoted 5 lines

The point is that the method provides access to the pointee, not the smart pointer itself. In fact it is perfectly fine to do a mem::swawp() for the pointee in the case of Box and depending on interpretation the sentence "does not let you swap the foreign-owned object for another" is confusing.

Yeah, I agree that the phrasing is somewhat confusing.

How about this:

/// 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.

Alice

#7 lore raw
Quoted 24 lines · Alice Ryhl
Quoted 13 lines · Andreas Hindborg

rust/kernel/types.rs line 64

Quoted 6 lines
rust/kernel/types.rs +6 -0
+    /// 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 this method does not let you swap the foreign-owned object for another. (That is, it
+    /// does not let you change the address of the void pointer that the foreign code is storing.)

How about this:

"For a smart pointer P<T> this method provides mutable access to T if &mut P<T> would allow mutable access to T. Otherwise it provides immutable access to T."

Quoted 5 lines

The point is that the method provides access to the pointee, not the smart pointer itself. In fact it is perfectly fine to do a mem::swawp() for the pointee in the case of Box and depending on interpretation the sentence "does not let you swap the foreign-owned object for another" is confusing.

Yeah, I agree that the phrasing is somewhat confusing.

How about this:

Quoted 10 lines

/// 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.

Sounds good 👍

BR Andreas

author maintainer
#8 lore raw
In reply to Andreas Hindborg (Samsung)
Quoted 44 lines · Andreas Hindborg
Quoted 44 lines
rust/kernel/sync/arc.rs +15 -11
index 172f563976a9..f152a562c9c3 100644
@@ -232,26 +232,35 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
 impl<T: 'static> ForeignOwnable for Arc<T> {
     type Borrowed<'a> = ArcBorrow<'a, T>;
+    // Mutable access to the `Arc` does not give any extra abilities over
+    // immutable access.
+    type BorrowedMut<'a> = ArcBorrow<'a, T>;
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         ManuallyDrop::new(self).ptr.as_ptr() as _
     }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
-        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
-        // a previous call to `Arc::into_foreign`.
-        let inner = NonNull::new(ptr as *mut ArcInner<T>).unwrap();
-
-        // SAFETY: The safety requirements of `from_foreign` ensure that the object remains alive
-        // for the lifetime of the returned value.
-        unsafe { ArcBorrow::new(inner) }
-    }
-
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
         // SAFETY: By the safety requirement of this function, we know that `ptr` came from
         // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and
         // holds a reference count increment that is transferrable to us.
-        unsafe { Self::from_inner(NonNull::new(ptr as _).unwrap()) }
+        unsafe { Self::from_inner(NonNull::new_unchecked(ptr as _)) }
     }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
+        // a previous call to `Arc::into_foreign`.
+        let inner = unsafe { NonNull::new_unchecked(ptr as *mut ArcInner<T>) };
+
+        // SAFETY: The safety requirements ensure that we will not give up our
+        // foreign-owned refcount while the `ArcBorrow` is still live.
+        unsafe { ArcBorrow::new(inner) }
+    }
+
Quoted 8 lines

rust/kernel/sync/arc.rs pub fn ptr_eq(this: &Self, other: &Self) -> bool { · line 264

Quoted 5 lines
rust/kernel/sync/arc.rs +5 -0
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: The safety requirements for `borrow_mut` are a superset of the safety
+        // requirements for `borrow`.
+        unsafe { Self::borrow(ptr) }
+    }

I am not sure this makes sense. How about splitting the trait in two, immutable and mutable and only implementing the immutable one or Arc?

I used this design based on what would make sense for a linked list. The idea is that we can have two different types of cursors for a linked
list: immutable and mutable. The immutable cursor lets you:

* move around the linked list
* access the values using borrow

The mutable cursor lets you:

* move around the linked list
* delete or add items to the list
* access the values using borrow_mut

The mutable cursor gives you extra abilities beyond the borrow vs borrow_mut distinction, so we want to provide both types of cursors even if the pointer type is Arc. To do that, we need a trait that defines what it means to have mutable access to an Arc.

Alice

#9 lore raw
Quoted 63 lines · Alice Ryhl
Quoted 44 lines · Andreas Hindborg
Quoted 44 lines
rust/kernel/sync/arc.rs +15 -11
index 172f563976a9..f152a562c9c3 100644
@@ -232,26 +232,35 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
 impl<T: 'static> ForeignOwnable for Arc<T> {
     type Borrowed<'a> = ArcBorrow<'a, T>;
+    // Mutable access to the `Arc` does not give any extra abilities over
+    // immutable access.
+    type BorrowedMut<'a> = ArcBorrow<'a, T>;
 
     fn into_foreign(self) -> *const core::ffi::c_void {
         ManuallyDrop::new(self).ptr.as_ptr() as _
     }
 
-    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
-        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
-        // a previous call to `Arc::into_foreign`.
-        let inner = NonNull::new(ptr as *mut ArcInner<T>).unwrap();
-
-        // SAFETY: The safety requirements of `from_foreign` ensure that the object remains alive
-        // for the lifetime of the returned value.
-        unsafe { ArcBorrow::new(inner) }
-    }
-
     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
         // SAFETY: By the safety requirement of this function, we know that `ptr` came from
         // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and
         // holds a reference count increment that is transferrable to us.
-        unsafe { Self::from_inner(NonNull::new(ptr as _).unwrap()) }
+        unsafe { Self::from_inner(NonNull::new_unchecked(ptr as _)) }
     }
+
+    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: By the safety requirement of this function, we know that `ptr` came from
+        // a previous call to `Arc::into_foreign`.
+        let inner = unsafe { NonNull::new_unchecked(ptr as *mut ArcInner<T>) };
+
+        // SAFETY: The safety requirements ensure that we will not give up our
+        // foreign-owned refcount while the `ArcBorrow` is still live.
+        unsafe { ArcBorrow::new(inner) }
+    }
+
Quoted 8 lines

rust/kernel/sync/arc.rs pub fn ptr_eq(this: &Self, other: &Self) -> bool { · line 264

Quoted 5 lines
rust/kernel/sync/arc.rs +5 -0
+    unsafe fn borrow_mut<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {
+        // SAFETY: The safety requirements for `borrow_mut` are a superset of the safety
+        // requirements for `borrow`.
+        unsafe { Self::borrow(ptr) }
+    }

I am not sure this makes sense. How about splitting the trait in two, immutable and mutable and only implementing the immutable one or Arc?

I used this design based on what would make sense for a linked list. The idea is that we can have two different types of cursors for a linked
list: immutable and mutable. The immutable cursor lets you:

* move around the linked list
* access the values using borrow

The mutable cursor lets you:

Quoted 8 lines

* move around the linked list
* delete or add items to the list
* access the values using borrow_mut

The mutable cursor gives you extra abilities beyond the borrow vs borrow_mut distinction, so we want to provide both types of cursors even if the pointer type is Arc. To do that, we need a trait that defines what it means to have mutable access to an Arc.

I don't see how that prevents this trait from being split in two?

BR Andreas

author maintainer
#10 lore raw
Quoted 16 lines · Andreas Hindborg
Quoted 16 lines
Quoted 2 lines

I am not sure this makes sense. How about splitting the trait in two, immutable and mutable and only implementing the immutable one or Arc?

I used this design based on what would make sense for a linked list. The idea is that we can have two different types of cursors for a linked
list: immutable and mutable. The immutable cursor lets you:

* move around the linked list
* access the values using borrow

The mutable cursor lets you:

* move around the linked list
* delete or add items to the list
* access the values using borrow_mut

Quoted 6 lines
Quoted 4 lines

The mutable cursor gives you extra abilities beyond the borrow vs borrow_mut distinction, so we want to provide both types of cursors even if the pointer type is Arc. To do that, we need a trait that defines what it means to have mutable access to an Arc.

I don't see how that prevents this trait from being split in two?

Well, you could split the trait, but if you make the mutable iterator require the borrow_mut trait, then you have to implement the mutable trait for Arc too if you want the mutable iterator to work with Arc.

And if you're always going to implement both traits, then maybe it makes more sense to not split the traits?

Alice

#11 lore raw
Quoted 22 lines · Alice Ryhl
Quoted 21 lines · Andreas Hindborg
Quoted 20 lines
Quoted 2 lines

I am not sure this makes sense. How about splitting the trait in two, immutable and mutable and only implementing the immutable one or Arc?

I used this design based on what would make sense for a linked list. The idea is that we can have two different types of cursors for a linked
list: immutable and mutable. The immutable cursor lets you:

* move around the linked list
* access the values using borrow

The mutable cursor lets you:

* move around the linked list
* delete or add items to the list
* access the values using borrow_mut

The mutable cursor gives you extra abilities beyond the borrow vs borrow_mut distinction, so we want to provide both types of cursors even if the pointer type is Arc. To do that, we need a trait that defines what it means to have mutable access to an Arc.

Quoted 8 lines
Quoted 1 line

I don't see how that prevents this trait from being split in two?

Well, you could split the trait, but if you make the mutable iterator require the borrow_mut trait, then you have to implement the mutable trait for Arc too if you want the mutable iterator to work with Arc.

And if you're always going to implement both traits, then maybe it makes more sense to not split the traits?

Maybe. Do you have a prototype for the list cursor available?

BR Andreas

#12 lore raw
In reply to Alice Ryhl
Quoted 24 lines · Alice Ryhl
Quoted 16 lines · Andreas Hindborg
Quoted 16 lines
Quoted 2 lines

I am not sure this makes sense. How about splitting the trait in two, immutable and mutable and only implementing the immutable one or Arc?

I used this design based on what would make sense for a linked list. The idea is that we can have two different types of cursors for a linked
list: immutable and mutable. The immutable cursor lets you:

* move around the linked list
* access the values using borrow

The mutable cursor lets you:

* move around the linked list
* delete or add items to the list
* access the values using borrow_mut

Quoted 6 lines
Quoted 4 lines

The mutable cursor gives you extra abilities beyond the borrow vs borrow_mut distinction, so we want to provide both types of cursors even if the pointer type is Arc. To do that, we need a trait that defines what it means to have mutable access to an Arc.

I don't see how that prevents this trait from being split in two?

Quoted 8 lines

Well, you could split the trait, but if you make the mutable iterator require the borrow_mut trait, then you have to implement the mutable trait for Arc too if you want the mutable iterator to work with Arc.

And if you're always going to implement both traits, then maybe it makes more sense to not split the traits?

Alice

I see this patch present in the rust-dev branch, but not in rust-next. Are there plans for including this patch in rust-next?

Cheers,
Ariel