"Implementing futures" page is probably misleading about `poll`

[montekki]

That page states the following in the comment section for the Future trait:

  /// The function that will be repeatedly called to see if the future is
    /// has completed or not. The `Async` enum can either be `Ready` or
    /// `NotReady` and indicates whether the future is ready to produce
    /// a value or not.

So you would expect that in a slightly modified HelloWorld example:

extern crate futures;
extern crate tokio;

use futures::{Future, Async, Poll};

struct HelloWorld(u32);

impl Future for HelloWorld {
        type Item = ();
        type Error = ();

        fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
                match self.0 {
                        42 => {
                                println!("The value is ready {}", self.0);
                                Ok(Async::Ready(()))
                        },
                        _ => {
                                self.0 += 1;
                                Ok(Async::NotReady)
                        },
                }
        }
}

fn main() {
        let future = HelloWorld(1);

        tokio::run(future);
}

tokio::run would continiously call poll on the future until it at some point returns Async::Ready, since the documentation also points out that:

Tokio is responsible for running futures to completion. This is done by passing the future to tokio::run.

However, that is not the case until you add task::current().notify() before returning Async::NotReady. Probably I haven't understood the whole case but it seems a bit misleading anyway.

[carllerche]

Thanks for the report.

Which section is this in? Do you have suggestions on how to improve the content to avoid confusion?