Struct tokio::io::unix::AsyncFd

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

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.

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. Changing the file descriptor 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. 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.

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 function 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. This function retains the waker for the last context that called poll_read_ready; it therefore can only be used by a single task at a time (however, poll_write_ready retains a second, independent waker).

This function 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.

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

Polls for write readiness. This function retains the waker for the last context that called poll_write_ready; it therefore can only be used by a single task at a time (however, poll_read_ready retains a second, independent waker).

This function 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.

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

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

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

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

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.