Understanding documentation of `AsyncFd` (in particular `AsyncFdReadyGurad`)

1

AsyncFd::ready returns an AsyncFdReadyGuard which is documented to be (emphasis mine)

returning a AsyncFdReadyGuard that must be dropped to resume polling for the requested ready states.

I think I understand the gist of the API: clear R/W readiness on the tokio side iff we did encounter R/W EWOULDBLOCK. What I don't understand is why the doc explicitly mentions the guard must be dropped to resume polling. The guard has no impl Drop and no further drop glue seems to be associated with it, so it seems to me nothing special is happening when it goes out of scope? I mean at the same time we do know that we may in fact manipulate AsyncFd in parallel:

Any number of tasks can query the same AsyncFd in parallel, on the same or different conditions.

Which seems to suggest that AsyncFd does not actually care how many AsyncFdReadyGuard exists out there anyway?

2

my guess is that you need to drop it so that it no longer holds a reference to the underlying io so that the polling can mutate it again

3

I think it's just bad wording of the documentation, or maybe it's just left over from old design where the guard did implement Drop.

the type AsyncFdReadyGuard is marked as #[must_use], and the lint message says:

"You must explicitly choose whether to clear the readiness state by calling a method on ReadyGuard"

it has nothing to do with Drop, so it's not an actual "guard" as in usual RAII terminology.