Skip to contentSkip to conversation

rust: sync: export lock::do_unlocked

PATCH Superseded Andreas Hindborg 3 participants 4 messages Jun 5 – Jun 8

Subsystems (3)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Andreas Hindborg

author reviewer
#0 lore raw

PATCH v2 1/1 rust: sync: export lock::do_unlocked

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

---
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/[email protected]

To: Peter Zijlstra <[email protected]>
To: Ingo Molnar <[email protected]>
To: Will Deacon <[email protected]>
To: Boqun Feng <[email protected]>
To: Waiman Long <[email protected]>
To: Miguel Ojeda <[email protected]>
To: Gary Guo <[email protected]>
To: Björn Roy Baron <[email protected]>
To: Benno Lossin <[email protected]>
To: Andreas Hindborg <[email protected]>
To: Alice Ryhl <[email protected]>
To: Trevor Gross <[email protected]>
To: Danilo Krummrich <[email protected]>
Cc: [email protected]
Cc: [email protected]

---
 rust/kernel/sync/lock.rs | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)
rust/kernel/sync/lock.rs +25 -1
index 10b6b5e9b024..9c549e469785 100644
@@ -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,

Signature · 1 line
Andreas Hindborg <[email protected]>
maintainer Reviewed-by on v2 1/1
#1 lore raw
Quoted 4 lines · Andreas Hindborg

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

Quoted 13 lines
 rust/kernel/sync/lock.rs | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)
rust/kernel/sync/lock.rs +1 -1
index 10b6b5e9b024..9c549e469785 100644
@@ -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.

rust/kernel/sync/lock.rs pub fn lock_ref(&self) -> &'a Lock<T, B> { · line 251

Quoted 10 lines
rust/kernel/sync/lock.rs +10 -0
+    ///
+    /// 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

author reviewer
#2 lore raw
Quoted 19 lines · Alice Ryhl
Quoted 4 lines · Andreas Hindborg

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

Quoted 11 lines
 rust/kernel/sync/lock.rs | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)
rust/kernel/sync/lock.rs +0 -0
index 10b6b5e9b024..9c549e469785 100644
@@ -238,7 +238,31 @@ pub fn lock_ref(&self) -> &'a Lock<T, B> {
         self.lock
     }
 
Quoted 14 lines

rust/kernel/sync/lock.rs pub fn lock_ref(&self) -> &'a Lock<T, B> { · line 251

Quoted 12 lines
rust/kernel/sync/lock.rs +11 -1
-    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

#3 lore raw
Quoted 2 lines · Andreas Hindborg

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