Struct tokio::io::unix::AsyncFd

pub struct AsyncFd<T: AsRawFd> { /* private fields */ }

Associates an IO object backed by a Unix file descriptor with the tokio reactor, allowing for readiness to be polled. The file descriptor must be of a type that can be used with the OS polling facilities (ie, poll, epoll, kqueue, etc), such as a network socket or pipe, and the file descriptor must have the nonblocking mode set to true.

Creating an AsyncFd registers the file descriptor with the current tokio Reactor, allowing you to directly await the file descriptor being readable or writable. Once registered, the file descriptor remains registered until the AsyncFd is dropped.

The AsyncFd takes ownership of an arbitrary object to represent the IO object. It is intended that this object will handle closing the file descriptor when it is dropped, avoiding resource leaks and ensuring that the AsyncFd can clean up the registration before closing the file descriptor. The AsyncFd::into_inner function can be used to extract the inner object to retake control from the tokio IO reactor.

The inner object is required to implement AsRawFd. This file descriptor must not change while AsyncFd owns the inner object, i.e. the AsRawFd::as_raw_fd method on the inner type must always return the same file descriptor when called multiple times. Failure to uphold this results in unspecified behavior in the IO driver, which may include breaking notifications for other sockets/etc.

Polling for readiness is done by calling the async functions readable and writable. These functions complete when the associated readiness condition is observed. Any number of tasks can query the same AsyncFd in parallel, on the same or different conditions.

On some platforms, the readiness detecting mechanism relies on edge-triggered notifications. This means that the OS will only notify Tokio when the file descriptor transitions from not-ready to ready. For this to work you should first try to read or write and only poll for readiness if that fails with an error of std::io::ErrorKind::WouldBlock.

Tokio internally tracks when it has received a ready notification, and when readiness checking functions like readable and writable are called, if the readiness flag is set, these async functions will complete immediately. This however does mean that it is critical to ensure that this ready flag is cleared when (and only when) the file descriptor ceases to be ready. The AsyncFdReadyGuard returned from readiness checking functions serves this function; after calling a readiness-checking async function, you must use this AsyncFdReadyGuard to signal to tokio whether the file descriptor is no longer in a ready state.

Use with to a poll-based API

In some cases it may be desirable to use AsyncFd from APIs similar to TcpStream::poll_read_ready. The AsyncFd::poll_read_ready and AsyncFd::poll_write_ready functions are provided for this purpose. Because these functions don’t create a future to hold their state, they have the limitation that only one task can wait on each direction (read or write) at a time.

Examples

This example shows how to turn std::net::TcpStream asynchronous using AsyncFd. It implements read as an async fn, and AsyncWrite as a trait to show how to implement both approaches.

use futures::ready;
use std::io::{self, Read, Write};
use std::net::TcpStream;
use std::pin::Pin;
use std::task::{Context, Poll};
use tokio::io::AsyncWrite;
use tokio::io::unix::AsyncFd;

pub struct AsyncTcpStream {
    inner: AsyncFd<TcpStream>,
}

impl AsyncTcpStream {
    pub fn new(tcp: TcpStream) -> io::Result<Self> {
        tcp.set_nonblocking(true)?;
        Ok(Self {
            inner: AsyncFd::new(tcp)?,
        })
    }

    pub async fn read(&self, out: &mut [u8]) -> io::Result<usize> {
        loop {
            let mut guard = self.inner.readable().await?;

            match guard.try_io(|inner| inner.get_ref().read(out)) {
                Ok(result) => return result,
                Err(_would_block) => continue,
            }
        }
    }
}

impl AsyncWrite for AsyncTcpStream {
    fn poll_write(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &[u8]
    ) -> Poll<io::Result<usize>> {
        loop {
            let mut guard = ready!(self.inner.poll_write_ready(cx))?;

            match guard.try_io(|inner| inner.get_ref().write(buf)) {
                Ok(result) => return Poll::Ready(result),
                Err(_would_block) => continue,
            }
        }
    }

    fn poll_flush(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<io::Result<()>> {
        // tcp flush is a no-op
        Poll::Ready(Ok(()))
    }

    fn poll_shutdown(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<io::Result<()>> {
        self.inner.get_ref().shutdown(std::net::Shutdown::Write)?;
        Poll::Ready(Ok(()))
    }
}

Implementations

impl<T: AsRawFd> AsyncFd<T>

pub fn new(inner: T) -> Result<Self> where
    T: AsRawFd, 

Creates an AsyncFd backed by (and taking ownership of) an object implementing AsRawFd. The backing file descriptor is cached at the time of creation.

This method must be called in the context of a tokio runtime.

pub fn with_interest(inner: T, interest: Interest) -> Result<Self> where
    T: AsRawFd, 

Creates new instance as new with additional ability to customize interest, allowing to specify whether file descriptor will be polled for read, write or both.

pub fn get_ref(&self) -> &T

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

pub fn get_mut(&mut self) -> &mut T

Returns a mutable reference to the backing object of this AsyncFd.

pub fn into_inner(self) -> T

Deregisters this file descriptor and returns ownership of the backing object.

pub fn poll_read_ready<'a>(
    &'a self,
    cx: &mut Context<'_>
) -> Poll<Result<AsyncFdReadyGuard<'a, T>>>

Polls for read readiness.

If the file descriptor is not currently ready for reading, this method will store a clone of the Waker from the provided Context. When the file descriptor becomes ready for reading, Waker::wake will be called.

Note that on multiple calls to poll_read_ready or poll_read_ready_mut, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup. (However, poll_write_ready retains a second, independent waker).

This method is intended for cases where creating and pinning a future via readable is not feasible. Where possible, using readable is preferred, as this supports polling from multiple tasks at once.

This method takes &self, so it is possible to call this method concurrently with other methods on this struct. This method only provides shared access to the inner IO resource when handling the AsyncFdReadyGuard.

pub fn poll_read_ready_mut<'a>(
    &'a mut self,
    cx: &mut Context<'_>
) -> Poll<Result<AsyncFdReadyMutGuard<'a, T>>>

Polls for read readiness.

If the file descriptor is not currently ready for reading, this method will store a clone of the Waker from the provided Context. When the file descriptor becomes ready for reading, Waker::wake will be called.

Note that on multiple calls to poll_read_ready or poll_read_ready_mut, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup. (However, poll_write_ready retains a second, independent waker).

This method is intended for cases where creating and pinning a future via readable is not feasible. Where possible, using readable is preferred, as this supports polling from multiple tasks at once.

This method takes &mut self, so it is possible to access the inner IO resource mutably when handling the AsyncFdReadyMutGuard.

pub fn poll_write_ready<'a>(
    &'a self,
    cx: &mut Context<'_>
) -> Poll<Result<AsyncFdReadyGuard<'a, T>>>

Polls for write readiness.

If the file descriptor is not currently ready for writing, this method will store a clone of the Waker from the provided Context. When the file descriptor becomes ready for writing, Waker::wake will be called.

Note that on multiple calls to poll_write_ready or poll_write_ready_mut, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup. (However, poll_read_ready retains a second, independent waker).

This method is intended for cases where creating and pinning a future via writable is not feasible. Where possible, using writable is preferred, as this supports polling from multiple tasks at once.

This method takes &self, so it is possible to call this method concurrently with other methods on this struct. This method only provides shared access to the inner IO resource when handling the AsyncFdReadyGuard.

pub fn poll_write_ready_mut<'a>(
    &'a mut self,
    cx: &mut Context<'_>
) -> Poll<Result<AsyncFdReadyMutGuard<'a, T>>>

Polls for write readiness.

If the file descriptor is not currently ready for writing, this method will store a clone of the Waker from the provided Context. When the file descriptor becomes ready for writing, Waker::wake will be called.

Note that on multiple calls to poll_write_ready or poll_write_ready_mut, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup. (However, poll_read_ready retains a second, independent waker).

This method is intended for cases where creating and pinning a future via writable is not feasible. Where possible, using writable is preferred, as this supports polling from multiple tasks at once.

This method takes &mut self, so it is possible to access the inner IO resource mutably when handling the AsyncFdReadyMutGuard.

pub async fn readable<'a>(&'a self) -> Result<AsyncFdReadyGuard<'a, T>>

Waits for the file descriptor to become readable, returning a AsyncFdReadyGuard that must be dropped to resume read-readiness polling.

This method takes &self, so it is possible to call this method concurrently with other methods on this struct. This method only provides shared access to the inner IO resource when handling the AsyncFdReadyGuard.

pub async fn readable_mut<'a>(
    &'a mut self
) -> Result<AsyncFdReadyMutGuard<'a, T>>

Waits for the file descriptor to become readable, returning a AsyncFdReadyMutGuard that must be dropped to resume read-readiness polling.

This method takes &mut self, so it is possible to access the inner IO resource mutably when handling the AsyncFdReadyMutGuard.

pub async fn writable<'a>(&'a self) -> Result<AsyncFdReadyGuard<'a, T>>

Waits for the file descriptor to become writable, returning a AsyncFdReadyGuard that must be dropped to resume write-readiness polling.

This method takes &self, so it is possible to call this method concurrently with other methods on this struct. This method only provides shared access to the inner IO resource when handling the AsyncFdReadyGuard.

pub async fn writable_mut<'a>(
    &'a mut self
) -> Result<AsyncFdReadyMutGuard<'a, T>>

Waits for the file descriptor to become writable, returning a AsyncFdReadyMutGuard that must be dropped to resume write-readiness polling.

This method takes &mut self, so it is possible to access the inner IO resource mutably when handling the AsyncFdReadyMutGuard.

Trait Implementations

impl<T: AsRawFd> AsRawFd for AsyncFd<T>

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl<T: Debug + AsRawFd> Debug for AsyncFd<T>

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

Formats the value using the given formatter.

impl<T: AsRawFd> Drop for AsyncFd<T>

fn drop(&mut self)

Executes the destructor for this type.