add async_io for AsyncFd

[folkertdev]

Motivation

In #5512, async_io was exposed on various socket types. However, for our work on ntpd-rs we would like this function to also be available on AsyncFd. We do some low-level epoll configuration there (specifically, listening for libc::EPOLLPRI on a separate file descriptor), so all we have is a file descriptor.

Solution

Expose the registration's async_io. The implementation is a single line. I believe that the implementation of Registration::async_io correctly clears the readiness flag, and that therefore use of AsyncFdReadyGuard is not needed here.

[folkertdev]

there is one other idea I had. The implementation could instead be

pub async fn async_io<R>(
    &self,
    interest: Interest,
    mut f: impl FnMut(&T) -> io::Result<R>,
) -> io::Result<R> {
    self.registration
        .async_io(interest, || f(self.get_ref()))
        .await
}

which changes usage to

let output = async_fd
    .async_io(Interest::WRITABLE, |inner| inner.send(buf))
    .await;

this makes the type signature inconsistent with the one for other types (but the same is already true for the signature of try_io), but I think it is nice that async_fd does not need to be repeated.

I'm not sure how to weigh these concerns: should the api be consistent, or is it better to deviate slightly if it is nicer for a particular type?

[folkertdev]

after thinking about it for a while, I think that second API I suggested is the better approach. It just makes using the API for this type more convenient, and the signature changes in a predictable way (try_io's signature follows the same pattern)

[Darksonn]

This raises the question of whether we want an FnMut(&T) or FnMut(&mut T). The other AsyncFd methods have a variant for both.

[folkertdev]

hmm, that would require two functions (so adding async_io_mut) maybe this is the reason the other async_ios don't provide the inner value? it works for try_io because there is a standard and a mutable guard.

I'm inclined to revert to the old api. thoughts?

[Darksonn]

Sorry for the delay. All of the other methods are duplicated, so I think it's fine for this one to be too.

[folkertdev]

ok, added it. Two questions from my side

• is this better than not giving the closure an argument (I think so)
• is the documentation for async_io_mut sufficient this way?

[Darksonn]

You can fix the FreeBSD ci failure by merging in master.

[Darksonn]

Just one more comment, then I think this is ready to be merged.

[Darksonn]

The documentation of a function should start with a short, single line description of what it does.

You can use the same one as the one on async_io_mut.

[folkertdev]

done

[Darksonn]

Thanks. LGTM.