Re: [PATCH] rust: sync: create the `get_mut()` function

[Boqun Feng <boqun.feng@gmail.com>]

Hi Guilherme,

Thanks for the patch. First I would prefer the title being:

	rust: sync: lock: Add Lock::get_mut()

"create" is not a good word to use here, and the parentheses after
"get_mut" already says it's a function.

On Thu, Jan 30, 2025 at 03:51:38PM -0300, Guilherme Giacomo Simoes wrote:
> Create a `get_mut()` function that receive a mutable instance of Lock,
> and return a mutable reference to data because if the instance is
> mutable, the rust compiler guarantee the access control.
> 

This commit log doesn't include "why we need this", so please add the
reason or the usage of this function, maybe you or someone need it
because of some initialization/setup code after creating a lock
protected object? Moreover...

> Suggested-by: Björn Roy Baron <bjorn3_gh@protonmail.com>
> Signed-off-by: Guilherme Giacomo Simoes <trintaeoitogc@gmail.com>
> ---
>  rust/kernel/sync/lock.rs | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> index eb80048e0110..3f9d78bcb37c 100644
> --- a/rust/kernel/sync/lock.rs
> +++ b/rust/kernel/sync/lock.rs
> @@ -140,6 +140,12 @@ pub fn new(t: T, name: &'static CStr, key: &'static LockClassKey) -> impl PinIni
>              }),
>          })
>      }
> +
> +    /// Get a mutable reference to data

... please provide an example of the usage in the doc.

> +    pub fn get_mut(&mut self) -> &mut T {
> +        // SAFETY: the caller must guarantee that the instance is only used in one place

SAFETY comments should explain why it's safe, here it's phrased like a
requirement, maybe something like:

    // SAFETY: `&mut self` guarantees the exclusive access to the
    // underlying data, therefore it's safe to reborrow the inner data.

Regards,
Boqun

> +        unsafe { &mut *self.data.get() }
> +    }
>  }
>  
>  impl<B: Backend> Lock<(), B> {
> -- 
> 2.34.1
>