Most locks in the linux kernel are stable, which means that holding the
lock is sufficient to keep the value from being freed. For example, this
means that if you acquire a lock on a refcounted value during rcu, then
you do not need to acquire a refcount to keep it alive past
rcu_read_unlock().

However, the Rust `Guard` type is written in a way where it cannot be
used with this pattern. One reason for this is the existence of the
`do_unlocked` method that is used with `Condvar`. The method allows you
to unlock the lock, run some code, and then reacquire the lock. This
operation is not okay if the lock itself is what keeps the value alive,
as it could be freed right after the unlock call.

If we want to support stable locks, we'll need a different guard type
that does not have a `do_unlocked` operation.

Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
 rust/kernel/sync/lock.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index 41dcddac69e2..7eab46d4060a 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -159,6 +159,17 @@ pub fn try_lock(&self) -> Option<Guard<'_, T, B>> {
 /// Allows mutual exclusion primitives that implement the [`Backend`] trait to automatically unlock
 /// when a guard goes out of scope. It also provides a safe and convenient way to access the data
 /// protected by the lock.
+///
+/// This guard may be released and reacquired with [`do_unlocked`]. Note that this implies that
+/// this `Guard` type is _not_ stable, that is, holding this lock is not sufficient to keep the
+/// underlying [`Lock`] alive. That must be done by some other mechanism such as a refcount or
+/// ownership.
+///
+/// # Invariants
+///
+/// This `Guard` owns the lock as defined by the [`Backend`] trait.
+///
+/// [`do_unlocked`]: Guard::do_unlocked
 #[must_use = "the lock unlocks immediately when the guard is unused"]
 pub struct Guard<'a, T: ?Sized, B: Backend> {
     pub(crate) lock: &'a Lock<T, B>,

---
base-commit: 40384c840ea1944d7c5a392e8975ed088ecf0b37
change-id: 20241205-guard-stable-doc-efad6812d0cb

Best regards,
-- 
Alice Ryhl <aliceryhl@google.com>

On Thu, Dec 05, 2024 at 12:35:51PM +0000, Alice Ryhl wrote:
> Most locks in the linux kernel are stable, which means that holding the
> lock is sufficient to keep the value from being freed. For example, this
> means that if you acquire a lock on a refcounted value during rcu, then
> you do not need to acquire a refcount to keep it alive past
> rcu_read_unlock().
> 
> However, the Rust `Guard` type is written in a way where it cannot be
> used with this pattern. One reason for this is the existence of the
> `do_unlocked` method that is used with `Condvar`. The method allows you
> to unlock the lock, run some code, and then reacquire the lock. This
> operation is not okay if the lock itself is what keeps the value alive,
> as it could be freed right after the unlock call.
> 

Hmm... but `Guard` holds a reference to the corresponding `Lock`. How
could this happen? Do you have an example?

Regards,
Boqun

> If we want to support stable locks, we'll need a different guard type
> that does not have a `do_unlocked` operation.
> 
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>
> ---
>  rust/kernel/sync/lock.rs | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> index 41dcddac69e2..7eab46d4060a 100644
> --- a/rust/kernel/sync/lock.rs
> +++ b/rust/kernel/sync/lock.rs
> @@ -159,6 +159,17 @@ pub fn try_lock(&self) -> Option<Guard<'_, T, B>> {
>  /// Allows mutual exclusion primitives that implement the [`Backend`] trait to automatically unlock
>  /// when a guard goes out of scope. It also provides a safe and convenient way to access the data
>  /// protected by the lock.
> +///
> +/// This guard may be released and reacquired with [`do_unlocked`]. Note that this implies that
> +/// this `Guard` type is _not_ stable, that is, holding this lock is not sufficient to keep the
> +/// underlying [`Lock`] alive. That must be done by some other mechanism such as a refcount or
> +/// ownership.
> +///
> +/// # Invariants
> +///
> +/// This `Guard` owns the lock as defined by the [`Backend`] trait.
> +///
> +/// [`do_unlocked`]: Guard::do_unlocked
>  #[must_use = "the lock unlocks immediately when the guard is unused"]
>  pub struct Guard<'a, T: ?Sized, B: Backend> {
>      pub(crate) lock: &'a Lock<T, B>,
> 
> ---
> base-commit: 40384c840ea1944d7c5a392e8975ed088ecf0b37
> change-id: 20241205-guard-stable-doc-efad6812d0cb
> 
> Best regards,
> -- 
> Alice Ryhl <aliceryhl@google.com>
>

On Thu, Dec 5, 2024 at 7:18 PM Boqun Feng <boqun.feng@gmail.com> wrote:
>
> On Thu, Dec 05, 2024 at 12:35:51PM +0000, Alice Ryhl wrote:
> > Most locks in the linux kernel are stable, which means that holding the
> > lock is sufficient to keep the value from being freed. For example, this
> > means that if you acquire a lock on a refcounted value during rcu, then
> > you do not need to acquire a refcount to keep it alive past
> > rcu_read_unlock().
> >
> > However, the Rust `Guard` type is written in a way where it cannot be
> > used with this pattern. One reason for this is the existence of the
> > `do_unlocked` method that is used with `Condvar`. The method allows you
> > to unlock the lock, run some code, and then reacquire the lock. This
> > operation is not okay if the lock itself is what keeps the value alive,
> > as it could be freed right after the unlock call.
> >
>
> Hmm... but `Guard` holds a reference to the corresponding `Lock`. How
> could this happen? Do you have an example?

Well it can't. The reference is yet another reason that Guard can't be
used for stable locking.

This doc change arises out of me needing a stable lock for something.

Alice

On Fri, Dec 06, 2024 at 10:56:23AM +0100, Alice Ryhl wrote:
> On Thu, Dec 5, 2024 at 7:18 PM Boqun Feng <boqun.feng@gmail.com> wrote:
> >
> > On Thu, Dec 05, 2024 at 12:35:51PM +0000, Alice Ryhl wrote:
> > > Most locks in the linux kernel are stable, which means that holding the
> > > lock is sufficient to keep the value from being freed. For example, this
> > > means that if you acquire a lock on a refcounted value during rcu, then
> > > you do not need to acquire a refcount to keep it alive past
> > > rcu_read_unlock().
> > >
> > > However, the Rust `Guard` type is written in a way where it cannot be
> > > used with this pattern. One reason for this is the existence of the
> > > `do_unlocked` method that is used with `Condvar`. The method allows you
> > > to unlock the lock, run some code, and then reacquire the lock. This
> > > operation is not okay if the lock itself is what keeps the value alive,
> > > as it could be freed right after the unlock call.
> > >
> >
> > Hmm... but `Guard` holds a reference to the corresponding `Lock`. How
> > could this happen? Do you have an example?
> 
> Well it can't. The reference is yet another reason that Guard can't be
> used for stable locking.
> 
> This doc change arises out of me needing a stable lock for something.
> 

Maybe it's better to put together this patch and the stable locking you
are working on? It's better for reviewing in that way.

I can see what a "stable lock' means, but want to make sure we change
the doc to reflect the exact requirement of a stable lock.

Regards,
Boqun

> Alice

On Fri, Dec 6, 2024 at 7:28 PM Boqun Feng <boqun.feng@gmail.com> wrote:
>
> On Fri, Dec 06, 2024 at 10:56:23AM +0100, Alice Ryhl wrote:
> > On Thu, Dec 5, 2024 at 7:18 PM Boqun Feng <boqun.feng@gmail.com> wrote:
> > >
> > > On Thu, Dec 05, 2024 at 12:35:51PM +0000, Alice Ryhl wrote:
> > > > Most locks in the linux kernel are stable, which means that holding the
> > > > lock is sufficient to keep the value from being freed. For example, this
> > > > means that if you acquire a lock on a refcounted value during rcu, then
> > > > you do not need to acquire a refcount to keep it alive past
> > > > rcu_read_unlock().
> > > >
> > > > However, the Rust `Guard` type is written in a way where it cannot be
> > > > used with this pattern. One reason for this is the existence of the
> > > > `do_unlocked` method that is used with `Condvar`. The method allows you
> > > > to unlock the lock, run some code, and then reacquire the lock. This
> > > > operation is not okay if the lock itself is what keeps the value alive,
> > > > as it could be freed right after the unlock call.
> > > >
> > >
> > > Hmm... but `Guard` holds a reference to the corresponding `Lock`. How
> > > could this happen? Do you have an example?
> >
> > Well it can't. The reference is yet another reason that Guard can't be
> > used for stable locking.
> >
> > This doc change arises out of me needing a stable lock for something.
> >
>
> Maybe it's better to put together this patch and the stable locking you
> are working on? It's better for reviewing in that way.

I'm not sure when that will happen.

> I can see what a "stable lock' means, but want to make sure we change
> the doc to reflect the exact requirement of a stable lock.
>
> Regards,
> Boqun
>
> > Alice