rust: sync: lock: Add an example for Guard::lock_ref()
Subsystems (3)
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
@@ -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) -> &'aLock <T ,B > { self.lock }
Signature · 1 line
2.39.5 (Apple Git-154)
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.Signed-off-by Boqun Feng <[email protected]>
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@@ -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) -> &'aLock <T ,B > { self.lock } --2.39.5 (Apple Git-154)
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.Signed-off-by Boqun Feng <[email protected]>Reviewed-by Benno Lossin <[email protected]>
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@@ -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,
BennoQuoted 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) -> &'aLock <T ,B > { self.lock } --2.39.5 (Apple Git-154)
Andreas Hindborg
reviewerQuoted 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.Signed-off-by Boqun Feng <[email protected]>---
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@@ -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
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.Signed-off-by Boqun Feng <[email protected]>---
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@@ -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
Andreas Hindborg
reviewerQuoted 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.Signed-off-by Boqun Feng <[email protected]>---
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@@ -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
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.Signed-off-by Boqun Feng <[email protected]>---
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@@ -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
Andreas Hindborg
reviewerQuoted 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.Signed-off-by Boqun Feng <[email protected]>---
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@@ -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
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.Signed-off-by Boqun Feng <[email protected]>---
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@@ -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
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.Signed-off-by Boqun Feng <[email protected]>
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
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.Signed-off-by Boqun Feng <[email protected]>Reviewed-by Alice Ryhl <[email protected]>
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
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
@@ -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) -> &'aLock <T ,B > { self.lock }