Async-Safe File Descriptors

In this lesson, you will learn how to safely wrap raw file descriptors within custom non-blocking I/O structures to ensure they integrate seamlessly with asynchronous executors.

The Challenge of Raw Descriptors

When working with custom I/O, you often deal with raw file descriptors (FDs). In an async environment, a raw FD is inherently synchronous—if you call read() on it and the data isn't ready, the entire thread blocks, halting your executor. To bridge this, we must create wrappers that track the FD's non-blocking state and interface properly with the reactor.

Wrapping the Descriptor

To manage an FD safely, your wrapper must own the resource and ensure it is closed exactly once when dropped. Use std::os::unix::io::RawFd as the underlying type, but wrap it in a struct that explicitly sets the descriptor to non-blocking mode:

use std::os::unix::io::{AsRawFd, RawFd};
use std::os::unix::io::IntoRawFd;
use libc::{fcntl, F_GETFL, F_SETFL, O_NONBLOCK};

pub struct AsyncFd {
    fd: RawFd,
}

impl AsyncFd {
    pub fn new(fd: RawFd) -> Self {
        // Set to non-blocking mode
        let flags = unsafe { fcntl(fd, F_GETFL, 0) };
        unsafe { fcntl(fd, F_SETFL, flags | O_NONBLOCK) };
        Self { fd }
    }
}

impl Drop for AsyncFd {
    fn drop(&mut self) {
        unsafe { libc::close(self.fd) };
    }
}

Safety in the Async Loop

Simply setting the O_NONBLOCK flag isn't enough; the wrapper must play nicely with your reactor. When your poll implementation (or AsyncRead/AsyncWrite implementation) attempts to perform an I/O operation, you will likely receive an EWOULDBLOCK or EAGAIN error.

Instead of panicking, your wrapper should register the FD with your reactor and return Poll::Pending. This signals to the executor that the task should be parked until the reactor receives an event notification (e.g., via epoll or kqueue) indicating the descriptor is ready for the next operation. By encapsulating this logic, you prevent the risk of leaking descriptors or blocking the entire thread pool during high-concurrency operations.

Key Takeaway: Always wrap raw file descriptors in a struct that enforces non-blocking mode and ensures proper cleanup via the Drop trait to prevent resource leaks and thread starvation.