Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FuturesUnordered guaranties #2837

Open
stormshield-gt opened this issue Mar 6, 2024 · 3 comments
Open

FuturesUnordered guaranties #2837

stormshield-gt opened this issue Mar 6, 2024 · 3 comments
Labels
A-stream Area: futures::stream docs

Comments

@stormshield-gt
Copy link

stormshield-gt commented Mar 6, 2024

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 ?

@stormshield-gt stormshield-gt changed the title FutureUnordered guaranties FuturesUnordered guaranties Mar 6, 2024
@aniaan
Copy link

aniaan commented Sep 24, 2024

That's the way it is

@nazar-pc
Copy link

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
Copy link
Member

taiki-e commented Oct 12, 2024

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.

@taiki-e taiki-e added docs A-stream Area: futures::stream labels Oct 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-stream Area: futures::stream docs
Projects
None yet
Development

No branches or pull requests

4 participants