Deconstructing the Future Trait & Polling Mechanics

The Pull-Based Async Model

Unlike languages with green threads (Go) or callback-based promises (JavaScript), Rust uses a poll-based state machine. Futures in Rust do nothing until polled:

pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll;
}

pub enum Poll {
    Ready(T),
    Pending,
}

Wakers & Non-Blocking Epoll Registration

When a Future returns Poll::Pending, it is legally required to register the Waker stored inside Context with a background event source (e.g. Linux epoll or Windows IOCP). When the kernel signals that the network socket is readable, the waker's wake() method schedules the top-level task back onto the executor's run queue:

// Intrusive Waker implementation pattern
pub struct SocketReadFuture<'a> {
    socket_fd: i32,
    buf: &'a mut [u8],
}

impl<'a> Future for SocketReadFuture<'a> {
    type Output = std::io::Result;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll {
        let res = unsafe {
            libc::read(self.socket_fd, self.buf.as_mut_ptr() as *mut _, self.buf.len())
        };

        if res >= 0 {
            Poll::Ready(Ok(res as usize))
        } else {
            let err = std::io::Error::last_os_error();
            if err.kind() == std::io::ErrorKind::WouldBlock {
                // Register waker with the epoll event loop
                EpollReactor::register(self.socket_fd, cx.waker().clone());
                Poll::Pending
            } else {
                Poll::Ready(Err(err))
            }
        }
    }
}