pub struct AsyncFdReadyGuard<'a, T: AsRawFd> { /* private fields */ }
Expand description

Represents an IO-ready event detected on a particular file descriptor that has not yet been acknowledged. This is a must_use structure to help ensure that you do not forget to explicitly clear (or not clear) the event.

This type exposes an immutable reference to the underlying IO object.

Implementations§

source§

impl<'a, Inner: AsRawFd> AsyncFdReadyGuard<'a, Inner>

source

pub fn clear_ready(&mut self)

Indicates to tokio that the file descriptor is no longer ready. The internal readiness flag will be cleared, and tokio will wait for the next edge-triggered readiness notification from the OS.

It is critical that this function not be called unless your code actually observes that the file descriptor is not ready. Do not call it simply because, for example, a read succeeded; it should be called when a read is observed to block.

source

pub fn retain_ready(&mut self)

This method should be invoked when you intentionally want to keep the ready flag asserted.

While this function is itself a no-op, it satisfies the #[must_use] constraint on the AsyncFdReadyGuard type.

source

pub fn try_io<R>( &mut self, f: impl FnOnce(&'a AsyncFd<Inner>) -> Result<R> ) -> Result<Result<R>, TryIoError>

Performs the provided IO operation.

If f returns a WouldBlock error, the readiness state associated with this file descriptor is cleared, and the method returns Err(TryIoError::WouldBlock). You will typically need to poll the AsyncFd again when this happens.

This method helps ensure that the readiness state of the underlying file descriptor remains in sync with the tokio-side readiness state, by clearing the tokio-side state only when a WouldBlock condition occurs. It is the responsibility of the caller to ensure that f returns WouldBlock only if the file descriptor that originated this AsyncFdReadyGuard no longer expresses the readiness state that was queried to create this AsyncFdReadyGuard.

Examples

This example sends some bytes to the inner std::net::UdpSocket. Waiting for write-readiness and retrying when the send operation does block are explicit. This example can be written more succinctly using AsyncFd::async_io.

use tokio::io::unix::AsyncFd;

use std::io;
use std::net::UdpSocket;

#[tokio::main]
async fn main() -> io::Result<()> {
    let socket = UdpSocket::bind("0.0.0.0:8080")?;
    socket.set_nonblocking(true)?;
    let async_fd = AsyncFd::new(socket)?;

    let written = loop {
        let mut guard = async_fd.writable().await?;
        match guard.try_io(|inner| inner.get_ref().send(&[1, 2])) {
            Ok(result) => {
                break result?;
            }
            Err(_would_block) => {
                // try_io already cleared the file descriptor's readiness state
                continue;
            }
        }
    };

    println!("wrote {written} bytes");

    Ok(())
}
source

pub fn get_ref(&self) -> &'a AsyncFd<Inner>

Returns a shared reference to the inner AsyncFd.

source

pub fn get_inner(&self) -> &'a Inner

Returns a shared reference to the backing object of the inner AsyncFd.

Trait Implementations§

source§

impl<'a, T: Debug + AsRawFd> Debug for AsyncFdReadyGuard<'a, T>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a, T> !RefUnwindSafe for AsyncFdReadyGuard<'a, T>

§

impl<'a, T> Send for AsyncFdReadyGuard<'a, T>where T: Sync,

§

impl<'a, T> Sync for AsyncFdReadyGuard<'a, T>where T: Sync,

§

impl<'a, T> Unpin for AsyncFdReadyGuard<'a, T>

§

impl<'a, T> !UnwindSafe for AsyncFdReadyGuard<'a, T>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.