Skip to contentSkip to conversation

rust: locks: Add `get_mut` method to `Lock`

PATCH Superseded Mathys-Gasnier 4 participants 5 messages Feb 22, 2024 – Feb 25, 2024 1 message not in the archive

Subsystems (3)

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 rust: locks: Add `get_mut` method to `Lock`

Having a mutable reference guarantees that no other threads have access to the lock, so we can take advantage of that to grant callers access to the protected data without the the cost of acquiring and releasing the locks. Since the lifetime of the data is tied to the mutable reference, the borrow checker guarantees that the usage is safe.

---
Changes in v3:
- Changing the function to take a Pin<&mut self> instead of a &mut self
- Removed reviewed-by's since big changes were made. Please take another
look.
- Link to v2: https://lore.kernel.org/r/[email protected]

Changes in v2:
- Improved doc comment.
- Link to v1: https://lore.kernel.org/r/[email protected]

---
 rust/kernel/sync/lock.rs | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)
rust/kernel/sync/lock.rs +15 -1
index f12a684bc957..0c8faf36d654 100644
@@ -7,7 +7,11 @@
 
 use super::LockClassKey;
 use crate::{bindings, init::PinInit, pin_init, str::CStr, types::Opaque, types::ScopeGuard};
-use core::{cell::UnsafeCell, marker::PhantomData, marker::PhantomPinned};
+use core::{
+    cell::UnsafeCell,
+    marker::{PhantomData, PhantomPinned},
+    pin::Pin,
+};
 use macros::pin_data;
 
 pub mod mutex;
@@ -121,6 +125,16 @@ pub fn lock(&self) -> Guard<'_, T, B> {
         // SAFETY: The lock was just acquired.
         unsafe { Guard::new(self, state) }
     }
+
+    /// Gets the data contained in the lock
+    /// Having a mutable reference to the lock guarantees that no other threads have access to the lock.
+    /// Making it safe to get a mutable reference to the lock content.
+    pub fn get_mut(self: Pin<&mut Self>) -> &mut T {
+        // SAFETY: Since the data is not pinned (No structural pinning for data).
+        // It is safe to get a mutable reference to the data and we never move the state.
+        let lock = unsafe { self.get_unchecked_mut() };
+        lock.data.get_mut()
+    }
 }
 
 /// A lock guard.

---
base-commit: 711cbfc717650532624ca9f56fbaf191bed56e67
change-id: 20240118-rust-locks-get-mut-c42072101d7a

Best regards,

Signature · 1 line
Mathys-Gasnier <[email protected]>
Reviewed-by on v3 1/1
#1 lore raw
Quoted 11 lines · On 2/22/24 13:26, Mathys-Gasnier via B4 Relay wrote:

From: Mathys-Gasnier <[email protected]>

Having a mutable reference guarantees that no other threads have access to the lock, so we can take advantage of that to grant callers access to the protected data without the the cost of acquiring and releasing the locks. Since the lifetime of the data is tied to the mutable reference, the borrow checker guarantees that the usage is safe.

---
[...]

This looks magnificent as is.

#2 lore raw
In reply to Mathys-Gasnier

Hi,

Thanks for the patch! Please see a few comments below.

Quoted 41 lines · On Thu, Feb 22, 2024 at 05:26:44PM +0100, Mathys-Gasnier via B4 Relay wrote:

From: Mathys-Gasnier <[email protected]>

Having a mutable reference guarantees that no other threads have access to the lock, so we can take advantage of that to grant callers access to the protected data without the the cost of acquiring and releasing the locks. Since the lifetime of the data is tied to the mutable reference, the borrow checker guarantees that the usage is safe.

---
Changes in v3:
- Changing the function to take a Pin<&mut self> instead of a &mut self
- Removed reviewed-by's since big changes were made. Please take another
look.
- Link to v2: https://lore.kernel.org/r/[email protected]

Changes in v2:
- Improved doc comment.
- Link to v1: https://lore.kernel.org/r/[email protected]

---
 rust/kernel/sync/lock.rs | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)
rust/kernel/sync/lock.rs +5 -1
index f12a684bc957..0c8faf36d654 100644
@@ -7,7 +7,11 @@
 
 use super::LockClassKey;
 use crate::{bindings, init::PinInit, pin_init, str::CStr, types::Opaque, types::ScopeGuard};
-use core::{cell::UnsafeCell, marker::PhantomData, marker::PhantomPinned};
+use core::{
+    cell::UnsafeCell,
+    marker::{PhantomData, PhantomPinned},
+    pin::Pin,
+};
 use macros::pin_data;
 
 pub mod mutex;

rust/kernel/sync/lock.rs pub fn lock(&self) -> Guard<'_, T, B> { · line 129

Quoted 5 lines
rust/kernel/sync/lock.rs +2 -0
@@ -121,6 +125,16 @@ pub fn lock(&self) -> Guard<'_, T, B> {
         // SAFETY: The lock was just acquired.
         unsafe { Guard::new(self, state) }
     }
+
+    /// Gets the data contained in the lock

This above line could use a period and a new line.

rust/kernel/sync/lock.rs pub fn lock(&self) -> Guard<'_, T, B> { · line 134

Quoted 5 lines
rust/kernel/sync/lock.rs +5 -0
+    /// Having a mutable reference to the lock guarantees that no other threads have access to the lock.
+    /// Making it safe to get a mutable reference to the lock content.
+    pub fn get_mut(self: Pin<&mut Self>) -> &mut T {
+        // SAFETY: Since the data is not pinned (No structural pinning for data).
+        // It is safe to get a mutable reference to the data and we never move the state.

Compare to "never move the state", a more accurate safety guarantee is "the &mut Self is only used to get the reference of the data field, therefore self won't get moved", I think.

BTW, while we are at it, I think we should document the "structural/non-structural pinning" design decisions somewhere, for example in the struct definition:

	#[pin_data]
	pub struct Lock<T: ?Sized, B: Backend> {
	    ...
	    /// The data protected by the lock.
	    /// This field is non-structural pinned.
	    pub(crate) data: UnsafeCell<T>,
	}

Thoughts? Or do we think "non-structural pinned" should be the default case so no need to document it? I want to have a clear document for each field to avoid the accidental "everyone forgets what's the decision here" ;-)

Regards,
Boqun

Quoted 15 lines
rust/kernel/sync/lock.rs +3 -1
+        let lock = unsafe { self.get_unchecked_mut() };
+        lock.data.get_mut()
+    }
 }
 
 /// A lock guard.
 
---

base-commit: 711cbfc717650532624ca9f56fbaf191bed56e67
change-id: 20240118-rust-locks-get-mut-c42072101d7a

Best regards,

Signature · 1 line
Mathys-Gasnier <[email protected]>
maintainer
#3 lore raw
Quoted 12 lines · Boqun Feng

BTW, while we are at it, I think we should document the "structural/non-structural pinning" design decisions somewhere, for example in the struct definition:

        #[pin_data]
        pub struct Lock<T: ?Sized, B: Backend> {
            ...
            /// The data protected by the lock.
            /// This field is non-structural pinned.
            pub(crate) data: UnsafeCell<T>,
        }
Quoted 4 lines

Thoughts? Or do we think "non-structural pinned" should be the default case so no need to document it? I want to have a clear document for each field to avoid the accidental "everyone forgets what's the decision here" ;-)

I would normally assume that "field is not marked #[pin]" implies that it's not structurally pinned. But it could still be worth to call out here.

I prefer the wording "not structurally pinnned" over "non-structural pinned".

Alice

A message that is not in the archive (sent off-list or not yet received): CAAZKF4B_YKZg+S=e7jnWDvcKJOXEJ_E0MRNmzEzEa013XZrYzw@mail.gmail.com

#5 lore raw
Quoted 2 lines · Mathys Gasnier

Should i include this comment in this patch ?

My suggestion is 1) in the comment of the get_mut() function, mention that "data is not structurally pinned, so return a &mut T here" and
2) in the function body of get_mut(), at the safety comments, you only need to put the reasoning explaining that self wouldn't get moved via the return value of self.get_unchecked_mut().

With these (along with the period and newline added), it'll be good to me.

Regards,
Boqun

Quoted 29 lines · Alice Ryhl
Quoted 28 lines · Boqun Feng
Quoted 12 lines

BTW, while we are at it, I think we should document the "structural/non-structural pinning" design decisions somewhere, for example in the struct definition:

        #[pin_data]
        pub struct Lock<T: ?Sized, B: Backend> {
            ...
            /// The data protected by the lock.
            /// This field is non-structural pinned.
            pub(crate) data: UnsafeCell<T>,
        }
Quoted 4 lines

Thoughts? Or do we think "non-structural pinned" should be the default case so no need to document it? I want to have a clear document for each field to avoid the accidental "everyone forgets what's the decision here" ;-)

I would normally assume that "field is not marked #[pin]" implies that it's not structurally pinned. But it could still be worth to call out here.

I prefer the wording "not structurally pinnned" over "non-structural pinned".

Alice