Skip to contentSkip to conversation

rust: sync: lock: Add an example for Guard::lock_ref()

PATCH Applied Boqun Feng 5 participants 12 messages Feb 23, 2025 – Mar 3, 2025

Subsystems (3)
lore
Share & tools
lore

Boqun Feng

author
#0 lore raw

PATCH 1/1 rust: sync: lock: Add an example for Guard::lock_ref()

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +24 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }
+    ///
+    /// // Creates a new lock on stack.
+    /// stack_pin_init!{
+    ///     let l = new_spinlock!(42)
+    /// }
+    ///
+    /// let g = l.lock();
+    ///
+    /// // `g` originates from `l`.
+    /// assert_held(&g, &l);
+    /// ```
     pub fn lock_ref(&self) -> &'a Lock<T, B> {
         self.lock
     }
Signature · 1 line
2.39.5 (Apple Git-154)
Reviewed-by on v1 1/1
#1 lore raw
Quoted 4 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

Quoted 23 lines

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +5 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.

rust/kernel/sync/lock.rs unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {} · line 218

Quoted 10 lines
rust/kernel/sync/lock.rs +10 -0
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }
+    ///
+    /// // Creates a new lock on stack.

I would be inclined to write "new lock on the stack.", but maybe that is incorrect.

---
Cheers,
Benno

Quoted 15 lines
rust/kernel/sync/lock.rs +9 -1
+    /// stack_pin_init!{
+    ///     let l = new_spinlock!(42)
+    /// }
+    ///
+    /// let g = l.lock();
+    ///
+    /// // `g` originates from `l`.
+    /// assert_held(&g, &l);
+    /// ```
     pub fn lock_ref(&self) -> &'a Lock<T, B> {
         self.lock
     }
--

2.39.5 (Apple Git-154)

author
#2 lore raw
Quoted 8 lines · Benno Lossin
Quoted 4 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

Thanks!

Quoted 28 lines
Quoted 28 lines

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +10 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
Quoted 9 lines

rust/kernel/sync/lock.rs unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {} · line 218

Quoted 5 lines
rust/kernel/sync/lock.rs +5 -0
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }
+    ///
+    /// // Creates a new lock on stack.

I would be inclined to write "new lock on the stack.", but maybe that is incorrect.

Yes, "on the stack" is better.

Regards,
Boqun

Quoted 20 lines

---
Cheers,
Benno

Quoted 15 lines
rust/kernel/sync/lock.rs +9 -1
+    /// stack_pin_init!{
+    ///     let l = new_spinlock!(42)
+    /// }
+    ///
+    /// let g = l.lock();
+    ///
+    /// // `g` originates from `l`.
+    /// assert_held(&g, &l);
+    /// ```
     pub fn lock_ref(&self) -> &'a Lock<T, B> {
         self.lock
     }
--

2.39.5 (Apple Git-154)

#3 lore raw
In reply to Boqun Feng
Quoted 25 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +3 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///

rust/kernel/sync/lock.rs unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {} · line 216

Quoted 10 lines
rust/kernel/sync/lock.rs +10 -0
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }

This seems super useful. Perhaps add this method as part of the lock api instead of just having it in the example?

Best regards,
Andreas Hindborg

#4 lore raw
Quoted 32 lines · Andreas Hindborg
Quoted 30 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +8 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
Quoted 8 lines

rust/kernel/sync/lock.rs unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {} · line 216

Quoted 5 lines
rust/kernel/sync/lock.rs +5 -0
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }

This seems super useful. Perhaps add this method as part of the lock api instead of just having it in the example?

I don't think it should be an assert. Instead make it return a Result<(), ()>. (or create better named unit error types)

---
Cheers,
Benno

#5 lore raw
Quoted 42 lines · Benno Lossin
Quoted 32 lines · Andreas Hindborg
Quoted 30 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +8 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
Quoted 8 lines

rust/kernel/sync/lock.rs unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {} · line 216

Quoted 5 lines
rust/kernel/sync/lock.rs +5 -0
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }

This seems super useful. Perhaps add this method as part of the lock api instead of just having it in the example?

Quoted 2 lines

I don't think it should be an assert. Instead make it return a Result<(), ()>. (or create better named unit error types)

No, this should not be part of usual control flow, and developers should not make control flow decisions based on this. It would always be an assertion. But you are right that assert! is probably not what we want. debug_assert! might be fine though.

Best regards,
Andreas Hindborg

#6 lore raw
Quoted 44 lines · Andreas Hindborg
Quoted 42 lines · Benno Lossin
Quoted 40 lines · Andreas Hindborg
Quoted 25 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +3 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///

rust/kernel/sync/lock.rs unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {} · line 216

Quoted 10 lines
rust/kernel/sync/lock.rs +10 -0
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }

This seems super useful. Perhaps add this method as part of the lock api instead of just having it in the example?

Quoted 7 lines
Quoted 2 lines

I don't think it should be an assert. Instead make it return a Result<(), ()>. (or create better named unit error types)

No, this should not be part of usual control flow, and developers should not make control flow decisions based on this. It would always be an assertion. But you are right that assert! is probably not what we want. debug_assert! might be fine though.

I agree, that it shouldn't be used for driver logic, but you still might want to warn/warn_once instead of panic (or debug_assert).

---
Cheers,
Benno

#7 lore raw
Quoted 48 lines · Benno Lossin
Quoted 47 lines · Andreas Hindborg
Quoted 44 lines · Benno Lossin
Quoted 32 lines · Andreas Hindborg
Quoted 30 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +8 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
Quoted 8 lines

rust/kernel/sync/lock.rs unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {} · line 216

Quoted 5 lines
rust/kernel/sync/lock.rs +5 -0
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }

This seems super useful. Perhaps add this method as part of the lock api instead of just having it in the example?

I don't think it should be an assert. Instead make it return a Result<(), ()>. (or create better named unit error types)

Quoted 7 lines
Quoted 4 lines

No, this should not be part of usual control flow, and developers should not make control flow decisions based on this. It would always be an assertion. But you are right that assert! is probably not what we want. debug_assert! might be fine though.

I agree, that it shouldn't be used for driver logic, but you still might want to warn/warn_once instead of panic (or debug_assert).

It might be useful to have an assert! that just does pr_once! on failed assertion. I sort of said I would pick up the pr_once! patches, so perhaps I should add that?

Best regards,
Andreas Hindborg

author
#8 lore raw
In reply to Andreas Hindborg
Quoted 32 lines · Andreas Hindborg
Quoted 30 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

---
This depends on Alice's patch:

	https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +8 -0
index 3701fac6ebf6..6d868e35b0a3 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
Quoted 9 lines

rust/kernel/sync/lock.rs unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {} · line 216

Quoted 5 lines
rust/kernel/sync/lock.rs +5 -0
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }

This seems super useful. Perhaps add this method as part of the lock api instead of just having it in the example?

I would like to have this (along with Alice's lock_ref()) for the upcoming Rust locking PR. So I'm going to keep it as a test now, but happy to see a patch (or write one if needed). Thoughts?

Regards,
Boqun

Quoted 7 lines

Best regards,
Andreas Hindborg

maintainer Reviewed-by on v1 1/1
#9 lore raw
In reply to Boqun Feng
Quoted 5 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

Quoted 5 lines

This depends on Alice's patch:

        https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

I think we can just keep two patches :)

Alice

author
#10 lore raw
Quoted 9 lines · Alice Ryhl
Quoted 5 lines · Boqun Feng

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

Thanks!

Quoted 8 lines
Quoted 5 lines

This depends on Alice's patch:

        https://lore.kernel.org/all/[email protected]/

I'm also OK to fold this in if Alice thinks it's fine.

I think we can just keep two patches :)

Fine by me.

Regards,
Boqun

Quoted 1 line

Alice

merge bot Applied
#11 lore raw
In reply to Boqun Feng
The following commit has been merged into the locking/core branch of tip:

The following commit has been merged into the locking/core branch of tip:

Commit-ID:     33530ab4613d7544ff43df2d690c54d8ff9288c6
Gitweb:        https://git.kernel.org/tip/33530ab4613d7544ff43df2d690c54d8ff9288c6
Author:        Boqun Feng <[email protected]>
AuthorDate:    Sat, 22 Feb 2025 23:09:24 -08:00
Committer:     Boqun Feng <[email protected]>
CommitterDate: Tue, 25 Feb 2025 08:52:48 -08:00

rust: sync: lock: Add an example for Guard::lock_ref()

To provide examples on usage of Guard::lock_ref() along with the unit test, an "assert a lock is held by a guard" example is added.

[boqun: Apply feedback from Benno]

---
 rust/kernel/sync/lock.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
rust/kernel/sync/lock.rs +24 -0
index 8e7e6d5..f53e87d 100644
@@ -201,6 +201,30 @@ unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
     /// Returns the lock that this guard originates from.
+    ///
+    /// # Examples
+    ///
+    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
+    /// lock is held.
+    ///
+    /// ```
+    /// # use kernel::{new_spinlock, stack_pin_init, sync::lock::{Backend, Guard, Lock}};
+    ///
+    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
+    ///     // Address-equal means the same lock.
+    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
+    /// }
+    ///
+    /// // Creates a new lock on the stack.
+    /// stack_pin_init!{
+    ///     let l = new_spinlock!(42)
+    /// }
+    ///
+    /// let g = l.lock();
+    ///
+    /// // `g` originates from `l`.
+    /// assert_held(&g, &l);
+    /// ```
     pub fn lock_ref(&self) -> &'a Lock<T, B> {
         self.lock
     }