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

[PATCH v3] 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>
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 {
         // SAFETY: The caller owns the lock, so it is safe to unlock it.
         unsafe { B::unlock(self.lock.state.get(), &self.state) };
 

---
base-commit: 72d3fcf802c45d00b300f25b848a93c3a2bd7c7e
change-id: 20260215-export-do-unlocked-00a6ac9373d4

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

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

[Gary Guo]

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.

Best,
Gary


>          // SAFETY: The caller owns the lock, so it is safe to unlock it.
>          unsafe { B::unlock(self.lock.state.get(), &self.state) };
>  
>
> ---
> base-commit: 72d3fcf802c45d00b300f25b848a93c3a2bd7c7e
> change-id: 20260215-export-do-unlocked-00a6ac9373d4
>
> Best regards,
> --  
> Andreas Hindborg <a.hindborg@kernel.org>

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

[Andreas Hindborg]

"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

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

[Boqun Feng]

On Tue, Sep 29, 2026 at 08:03:20PM +0200, Andreas Hindborg wrote:
> "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.
> 

I didn't find a unlocked() in spin. You mean
https://crates.io/crates/lock_api ?

To me, `do_unlocked()` is better, since it indicates something is going
to be done after the lock being dropped.

Regards,
Boqun

> 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
> 
> 
> 

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

[Gary Guo]

On Wed Sep 30, 2026 at 2:45 PM BST, Boqun Feng wrote:
> On Tue, Sep 29, 2026 at 08:03:20PM +0200, Andreas Hindborg wrote:
>> "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.
>> 
>
> I didn't find a unlocked() in spin. You mean
> https://crates.io/crates/lock_api ?

Right, both of them share the common interface via lock_api.

> To me, `do_unlocked()` is better, since it indicates something is going
> to be done after the lock being dropped.

I think that indication is usually "with". So `guard.with_unlocked(|| action)`.

From my experience in Rust code "do_" is quite commonly the internal helper for
a public API.

Best,
Gary