In order for callers to be able to access the inner T safely if T: !Unpin,
there needs to be a way to get a Pin<&mut T>. Add this accessor and a
corresponding example to tell users how it works.

This is not useful on its own for now, because we do not support pin
projections yet. This means that the following is not going to compile:

    let mut data: MutexGuard<'_, Data> = mutex.lock();
    let mut data: Pin<&mut Data> = data.as_mut();
    let foo = &mut data.foo;

A future patch can enable the behavior above by implementing support for
pin projections.

Link: https://github.com/Rust-for-Linux/linux/issues/1181
Suggested-by: Benno Lossin <lossin@kernel.org>
Suggested-by: Boqun Feng <boqun.feng@gmail.com>
Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
---
 rust/kernel/sync/lock.rs | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index 087bc0391f92a73b9af18ca31461b513bb5a9bcd..27857659a7f1ba4a8b844bb18d009d037e0c5b03 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -243,6 +243,25 @@ pub(crate) fn do_unlocked<U>(&mut self, cb: impl FnOnce() -> U) -> U {
 
         cb()
     }
+
+    /// Returns a pinned mutable reference to the protected data.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    ///     # use kernel::sync::{Mutex, MutexGuard};
+    ///     # use core::pin::Pin;
+    ///     struct Data;
+    ///
+    ///     fn example(mutex: &Mutex<Data>) {
+    ///         let mut data: MutexGuard<'_, Data> = mutex.lock();
+    ///         let mut data: Pin<&mut Data> = data.as_mut();
+    ///     }
+    /// ```
+    pub fn as_mut(&mut self) -> Pin<&mut T> {
+        // SAFETY: `self.lock.data` is structurally pinned.
+        unsafe { Pin::new_unchecked(&mut *self.lock.data.get()) }
+    }
 }
 
 impl<T: ?Sized, B: Backend> core::ops::Deref for Guard<'_, T, B> {

-- 
2.50.1

On Wed Jul 30, 2025 at 7:14 PM CEST, Daniel Almeida wrote:
> In order for callers to be able to access the inner T safely if T: !Unpin,
> there needs to be a way to get a Pin<&mut T>. Add this accessor and a
> corresponding example to tell users how it works.
>
> This is not useful on its own for now, because we do not support pin
> projections yet. This means that the following is not going to compile:
>
>     let mut data: MutexGuard<'_, Data> = mutex.lock();
>     let mut data: Pin<&mut Data> = data.as_mut();
>     let foo = &mut data.foo;
>
> A future patch can enable the behavior above by implementing support for
> pin projections.

I am currently working on a patch that adds pin projections to
`#[pin_data]`. It will most likely land in v6.18.

> Link: https://github.com/Rust-for-Linux/linux/issues/1181
> Suggested-by: Benno Lossin <lossin@kernel.org>
> Suggested-by: Boqun Feng <boqun.feng@gmail.com>
> Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
> ---
>  rust/kernel/sync/lock.rs | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
>
> diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> index 087bc0391f92a73b9af18ca31461b513bb5a9bcd..27857659a7f1ba4a8b844bb18d009d037e0c5b03 100644
> --- a/rust/kernel/sync/lock.rs
> +++ b/rust/kernel/sync/lock.rs
> @@ -243,6 +243,25 @@ pub(crate) fn do_unlocked<U>(&mut self, cb: impl FnOnce() -> U) -> U {
>  
>          cb()
>      }
> +
> +    /// Returns a pinned mutable reference to the protected data.
> +    ///

I would mention that the guard implements `DerefMut` when `T: Unpin`, so
in that case it is probably easier to use that instead of calling this
function.

> +    /// # Examples
> +    ///
> +    /// ```
> +    ///     # use kernel::sync::{Mutex, MutexGuard};
> +    ///     # use core::pin::Pin;
> +    ///     struct Data;
> +    ///
> +    ///     fn example(mutex: &Mutex<Data>) {
> +    ///         let mut data: MutexGuard<'_, Data> = mutex.lock();
> +    ///         let mut data: Pin<&mut Data> = data.as_mut();
> +    ///     }

No need to indent the code in the example.

---
Cheers,
Benno

> +    /// ```
> +    pub fn as_mut(&mut self) -> Pin<&mut T> {
> +        // SAFETY: `self.lock.data` is structurally pinned.
> +        unsafe { Pin::new_unchecked(&mut *self.lock.data.get()) }
> +    }
>  }
>  
>  impl<T: ?Sized, B: Backend> core::ops::Deref for Guard<'_, T, B> {