Re: [PATCH v2] rust: doc: Clarify safety invariants for Revocable type

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

On Sat May 17, 2025 at 2:03 AM CEST, Marcelo Moreira wrote:
> Hello guys!
>
> Thank you for the continued feedback =)
>
> Based on your point, I'm revising the `# Invariants` section for `Revocable<T>`
> to be more precise about when access to `data` is valid. I'm
> considering the following wording:
>
> - data is valid if and only if is_available is true.
> - Access to data is valid while the RCU read-side lock is held, ensuring no
> concurrent revocation, or within the specific scope of the
> revoke_internal function
> where the revocation logic guarantees exclusive access before dropping data.

How about we combine these two into:

* `data` is valid for reads if the RCU read-side lock is held and
  `is_available` was true after taking the lock.

>  - Once is_available is set to false, further access to data outside
> of the revocation
> process is disallowed, and the object is dropped either after an RCU
> grace period
> (in [revoke]), or immediately (in [revoke_nosync]).

I wouldn't name the functions, since there might be more added. How
about:
* `is_available` is only set to `false` once; that thread takes
  ownership of `data`.

Let's also see what Danilo thinks.

---
Cheers,
Benno

> I've attempted to clarify that the RCU read-side lock protects against
> concurrent
> revocation during normal access, but that `revoke_internal` has its own safety
> guarantees that allow access without the lock in that specific context. I
> 'd appreciate your feedback on this revised wording to ensure it accurately
> reflects the intended behavior and safety invariants.
>
> Thank you for your patience and guidance. I will send the next version
> of the patch soon.
>
> Best regards,
> Marcelo Moreira