FuturesUnordered guaranties

[stormshield-gt]

In the documentation of FuturesUnordered it's written

"When new futures are added, poll_next must be called in order to begin receiving wake-ups for new futures."

Does it mean that if I consume the FuturesUnordered as a Stream and there is no more futures inside it, it would return None but if then later I add a future, it will return Some again?

In the current implementation, this seems to be the case:

use std::time::Duration;

use futures::stream::{FusedStream, FuturesUnordered};
use futures::StreamExt;

fn main() {
   tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap().block_on(run())
}

async fn run() {
   let mut fuo = [f(), f()].into_iter().collect::<FuturesUnordered<_>>();

   assert!(fuo.next().await.is_some());
   assert!(fuo.next().await.is_some());
   assert!(fuo.next().await.is_none());

   assert!(fuo.is_terminated());

   fuo.push(f());

   assert!(fuo.next().await.is_some());

   println!("Done !");
}

async fn f() {
   tokio::time::sleep(Duration::from_millis(100)).await;
}

PlayGround Link

Is it a behavior I can rely upon? In other words, is this guarantee by FuturesUnordered ?

[aniaan]

That's the way it is

[nazar-pc]

I wondered the same and would appreciate to have this documented if it is indeed something that is guaranteed to be the case going forward to avoid unexpected breakage.

I saw some projects depending on this behavior already, for example https://github.com/paritytech/polkadot-sdk uses this in the networking stack implementation.

[taiki-e]

if I consume the FuturesUnordered as a Stream and there is no more futures inside it, it would return None but if then later I add a future, it will return Some again?

Is it a behavior I can rely upon? In other words, is this guarantee by FuturesUnordered ?

Yes. This is a guaranteed behavior. (Relevant test is here.)

I would accept a PR to expand documentation to clarify the guarantee here.