Poll Method in Rust

The poll method is a fundamental component of the asynchronous programming model in Rust, specifically within the Future trait. It is utilized by the async runtime to determine the state of an asynchronous computation. The method's primary role is to check if a computation has completed and to return the result if available.

Definition and Functionality

The poll method is defined as part of the Future trait in Rust. It is invoked by the async runtime to attempt to resolve a future into its final value. The method returns a Poll enum, which can be one of two variants:

  • Poll::Pending: Indicates that the future is not ready yet, and the computation is still ongoing.
  • Poll::Ready(val): Indicates that the computation has completed successfully, and the result val is available.

The poll method is crucial for the functioning of asynchronous programs, as it allows the async runtime to manage and schedule tasks efficiently.

Implementation of the Future Trait

The Future trait in Rust is defined as follows:

pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}
  • type Output: Represents the data type returned when a future successfully completes.
  • poll: The method that checks the readiness of the future. It takes a pinned reference to the future and a mutable reference to a Context object.

Example: Custom Future Implementation

To understand how futures work, consider the following example of a custom future:

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::thread::sleep;
use std::time::Duration;

struct ReadFileFuture {}

impl Future for ReadFileFuture {
    type Output = String;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        println!("Tokio! Stop polling me");
        cx.waker().wake_by_ref();
        Poll::Ready(String::from("Hello, there from file 1"))
    }
}

#[tokio::main]
async fn main() {
    println!("Hello before reading file!");

    let h1 = tokio::spawn(async {
        let future1 = ReadFileFuture {};
        println!("{:?}", future1.await);
    });

    let h2 = tokio::spawn(async {
        let file2_contents = read_from_file2().await;
        println!("{:?}", file2_contents);
    });
    let _ = tokio::join!(h1, h2);
}

// function that simulates reading from a file
fn read_from_file2() -> impl Future<Output = String> {
    async {
        sleep(Duration::new(2, –));
        String::from("Hello, there from file 2")
    }
}

In this example, the ReadFileFuture struct implements the Future trait. The poll method is overridden to return Poll::Ready with a string value, simulating the completion of an asynchronous task.

Figures

[Figure 10.8](https://livebook.manning.com/book/rust-servers-services-and-apps/chapter-10/183)

Figure 10.8 Spawning async tasks with futures, step 1 Figure 10.8 Spawning async tasks with futures, step 1

[Figure 10.11](https://livebook.manning.com/book/rust-servers-services-and-apps/chapter-10/183)

Figure 10.11 Custom future with Poll::Ready, step 3 Figure 10.11 Custom future with Poll::Ready, step 3

These figures illustrate the process of spawning async tasks and the flow of a custom future returning Poll::Ready.