On Tue Jun 23, 2026 at 8:09 AM CEST, Philipp Stanner wrote:
> The reason I wrote "typically" is because my mind had the potential
> future use-case of ours prefetched where we might have to do a
> synchronize_rcu() to wait for a C backend to be done with something,
> where no one really holds a Rust `Guard` (though of course the read
> lock).
In that case I'd just say "read side critical section" and then mention the
rcu::Guard type as one way to end up in such.
In comparison with other synchronization primitives, RCU is a global mechanism,
so only talking about the rcu::Guard specifically might indeed be misleading.
>> Also, while it's implicit, it might still be worth to explicitly call out
>> that
>> this means concurrently held Guard objects (concurrent read side critical
>> sections), i.e. subsequent read side critical sections may still run
>> concurrently.
>
> That's quite generic RCU knowledge IMO. I'm not sure to what degree one
> wants to document RCU in general at this new function here, vs just the
> Rust API.
One or two precise sentences should be enough; no need to document RCU in
general.
> Rewording the documentation is fine by me, but since we're in a nitty
> domain here I would then ask you to provide a few draft sentences that
> would satisfy your basic requirements.
Should be as simple as adding "in progress", e.g. considering the above:
This waits for all RCU read-side critical sections already in progress,
including those established by an [`rcu::Guard`].
This does not prevent new read-side critical sections from starting;
those may begin and run while this call blocks.
