Re: [PATCH v6 3/3] rust: revocable: Document RevocableGuard invariants and refine Deref safety

["Benno Lossin" <lossin@kernel.org>]

On Tue Jul 8, 2025 at 2:33 AM CEST, Marcelo Moreira wrote:
> Improves the `RevocableGuard` documentation by explicitly stating that
> its `data_ref` member is a valid pointer as an invariant. Additionally,
> the `Deref` implementation's `SAFETY` comment is refined to justify
> the `unsafe` dereference based on this new invariant and the
> `_rcu_guard` ensuring data accessibility.
>
> These changes address feedback regarding the clarity and completeness
> of `RevocableGuard`'s safety guarantees.
>
> Signed-off-by: Marcelo Moreira <marcelomoreira1905@gmail.com>
> ---
>  rust/kernel/revocable.rs | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/rust/kernel/revocable.rs b/rust/kernel/revocable.rs
> index 6d8e9237dbdf..64fe44b4f5a3 100644
> --- a/rust/kernel/revocable.rs
> +++ b/rust/kernel/revocable.rs
> @@ -233,7 +233,8 @@ fn drop(self: Pin<&mut Self>) {
>  ///
>  /// # Invariants
>  ///
> -/// The RCU read-side lock is held while the guard is alive.
> +/// - `data_ref` is a valid pointer to a `T` object for the entire lifetime of this guard.

This should be:

    /// - `data_ref` is a valid pointer for as long as the RCU read-side lock is held.

> +/// - The RCU read-side lock is held while the guard is alive.

And this invariant is unnecessary.

>  pub struct RevocableGuard<'a, T> {
>      // This can't use the `&'a T` type because references that appear in function arguments must
>      // not become dangling during the execution of the function, which can happen if the
> @@ -258,8 +259,8 @@ impl<T> Deref for RevocableGuard<'_, T> {
>      type Target = T;
>  
>      fn deref(&self) -> &Self::Target {
> -        // SAFETY: By the type invariants, we hold the rcu read-side lock, so the object is
> -        // guaranteed to remain valid.
> +        // SAFETY: `self.data_ref` is valid for writes because of `Self`'s type invariants,
> +        // and `_rcu_guard` ensures the data's accessibility for the lifetime of this guard.

This also needs to be adjusted.

Also this patch should fix any invariant comments needed to construct
`RevocableGuard`.

---
Cheers,
Benno

>          unsafe { &*self.data_ref }
>      }
>  }