Re: [PATCH v3] rust: sync: export lock::do_unlocked

[Andreas Hindborg <a.hindborg@kernel.org>]

"Gary Guo" <gary@garyguo.net> writes:

> On Tue Sep 29, 2026 at 3:45 PM BST, Andreas Hindborg wrote:
>> Export lock::do_unlocked publicly. Add documentation for the method.
>>
>> Reviewed-by: Benno Lossin <lossin@kernel.org>
>> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
>> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
>> ---
>> Changes in v3:
>> - Rebase on v7.3-rc5.
>> - Do not import prelude in example (Alice).
>> - Link to v2: https://msgid.link/20260605-export-do-unlocked-v2-1-e23001390231@kernel.org
>>
>> Changes in v2:
>> - Drop spurious space before `guard.do_unlocked` in the doc example (Benno).
>> - Un-hide the imports in the doc example so the rendered docs no longer have a spurious blank line after them (Alice).
>> - Link to v1: https://msgid.link/20260215-export-do-unlocked-v1-1-f5cd2203b20f@kernel.org
>> ---
>>  rust/kernel/sync/lock.rs | 26 +++++++++++++++++++++++++-
>>  1 file changed, 25 insertions(+), 1 deletion(-)
>>
>> diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
>> index 10b6b5e9b024..edfff9e10199 100644
>> --- a/rust/kernel/sync/lock.rs
>> +++ b/rust/kernel/sync/lock.rs
>> @@ -238,7 +238,31 @@ pub fn lock_ref(&self) -> &'a Lock<T, B> {
>>          self.lock
>>      }
>>
>> -    pub(crate) fn do_unlocked<U>(&mut self, cb: impl FnOnce() -> U) -> U {
>> +    /// Temporarily unlock the lock to execute the given closure.
>> +    ///
>> +    /// This method unlocks the lock before calling the closure `cb`, and re-locks it afterwards.
>> +    /// This is useful when you need to perform operations that are not allowed while holding
>> +    /// certain locks, such as allocating memory (which is prohibited while holding a spinlock).
>> +    ///
>> +    /// # Examples
>> +    ///
>> +    /// ```
>> +    /// use kernel::new_spinlock;
>> +    /// use pin_init::stack_pin_init;
>> +    ///
>> +    /// stack_pin_init!{
>> +    ///     let lock = new_spinlock!(())
>> +    /// }
>> +    ///
>> +    /// let mut guard = lock.lock();
>> +    /// let mut buffer = KVec::new();
>> +    /// // Temporarily unlock to allocate memory, which should not be done while holding a spinlock.
>> +    /// guard.do_unlocked(|| {
>> +    ///     buffer.push(5u32, GFP_KERNEL)
>> +    /// })?;
>> +    /// # Ok::<(), Error>(())
>> +    /// ```
>> +    pub fn do_unlocked<U>(&mut self, cb: impl FnOnce() -> U) -> U {
>
> Do we want to keep the name `do_unlocked` now this is public?
>
> I think we can drop "do_" and just call this `unlocked`, consistent with popular
> Rust ecosystem crates like parking_lot and spin.

If this is the established way, I think we should do that.

I don't think we need a new version of the patch, just fix it during
apply?

Best regards,
Andreas Hindborg