io: add get_{ref,mut} methods to AsyncFdReadyGuard and AsyncFdReadyMutGuard. - #3807

The only way to use AsyncFdReadyMutGuard currently is through try_io, since it is impossible to access the underlying object. In some situations, it is desirable to use clear_ready and retain_ready directly instead of try_io. Enable this by adding get_ref and get_mut methods.

Motivation

When using AsyncFd with an I/O object that does not communicate readiness through ErrorKind::WouldBlock, code using try_io becomes hard to read. In the following example, the next() method returns None when no new data is ready.

let mut guard = ready!(self.inner.poll_read_ready_mut(cx))?;

match guard.try_io(|s| {
    s.get_mut()
        .next()
        .ok_or_else(|| ErrorKind::WouldBlock.into())
}) {
    Ok(event) => Poll::Ready(Some(event)),
    Err(_) => Poll::Pending,
}

As seen here, you have to explicitly convert None to a WouldBlock error in try_io, only to convert that error back into Pending afterwards. This is confusing to read.

Solution

By adding AsyncFdReadyMutGuard::get_mut, this can be expressed in a more straight-forward way:

let mut guard = ready!(self.inner.poll_read_ready_mut(cx))?;

match guard.get_mut().get_mut().next() {
    Some(event) => {
        guard.retain_ready();
        Poll::Ready(Some(Ok(event)))
    }
    None => {
        guard.clear_ready();
        Poll::Pending
    }
}

The get_ref methods are added for consistency.

Questions

Should we return a reference to AsyncFd<T> or T? try_io uses AsyncFd<T> in its argument, so the proposed solution is consistent. On the other hand, in probably all cases, this requires writing guard.get_mut().get_mut().