[PATCH v2] rust: sync: export lock::do_unlocked

[PATCH v2] rust: sync: export lock::do_unlocked

[Andreas Hindborg]

Export lock::do_unlocked publicly. Add documentation for the method.

Reviewed-by: Benno Lossin <lossin@kernel.org>
Signed-off-by: Andreas Hindborg <a.hindborg@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

To: Peter Zijlstra <peterz@infradead.org>
To: Ingo Molnar <mingo@redhat.com>
To: Will Deacon <will@kernel.org>
To: Boqun Feng <boqun@kernel.org>
To: Waiman Long <longman@redhat.com>
To: Miguel Ojeda <ojeda@kernel.org>
To: Gary Guo <gary@garyguo.net>
To: Björn Roy Baron <bjorn3_gh@protonmail.com>
To: Benno Lossin <lossin@kernel.org>
To: Andreas Hindborg <a.hindborg@kernel.org>
To: Alice Ryhl <aliceryhl@google.com>
To: Trevor Gross <tmgross@umich.edu>
To: Danilo Krummrich <dakr@kernel.org>
Cc: linux-kernel@vger.kernel.org
Cc: rust-for-linux@vger.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..9c549e469785 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, prelude::*};
+    /// 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 {
         // SAFETY: The caller owns the lock, so it is safe to unlock it.
         unsafe { B::unlock(self.lock.state.get(), &self.state) };
 

---
base-commit: 7fd2df204f342fc17d1a0bfcd474b24232fb0f32
change-id: 20260215-export-do-unlocked-00a6ac9373d4

Best regards,
--  
Andreas Hindborg <a.hindborg@kernel.org>

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

[Alice Ryhl]

On Fri, Jun 05, 2026 at 02:57:07PM +0200, Andreas Hindborg wrote:
> Export lock::do_unlocked publicly. Add documentation for the method.
> 
> Reviewed-by: Benno Lossin <lossin@kernel.org>
> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

>  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..9c549e469785 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, prelude::*};
> +    /// use pin_init::stack_pin_init;

I think the prelude is imported automatically.

Alice

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

[Andreas Hindborg]

Alice Ryhl <aliceryhl@google.com> writes:

> On Fri, Jun 05, 2026 at 02:57:07PM +0200, Andreas Hindborg wrote:
>> Export lock::do_unlocked publicly. Add documentation for the method.
>> 
>> Reviewed-by: Benno Lossin <lossin@kernel.org>
>> Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
>
> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
>
>>  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..9c549e469785 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, prelude::*};
>> +    /// use pin_init::stack_pin_init;
>
> I think the prelude is imported automatically.

Is this part of our kunit harness?

Best regards,
Andreas Hindborg

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

[Miguel Ojeda]

On Mon, Jun 8, 2026 at 10:34 AM Andreas Hindborg <a.hindborg@kernel.org> wrote:
>
> Is this part of our kunit harness?

Yeah, I had it there since the beginning, i.e. no worries about
backports or things like that, if that is what you mean.

Cheers,
Miguel