Add Future::join

[yoshuawuyts]

In the 2016 futures announcement post, the join combinator was shown as something that would make choosing between several futures easy.

In rust-lang/futures-rs#1215 and beyond this was changed to several methods: join, join1, join2, join3, and join!, try_join macros (proc macros since 0.3.0-alpha.18 so statements can be written inline).

Future::join

It still seems incredibly useful to be able to join multiple futures together, and having a single combinator to do that seems like the simplest API, even if resulting code might not look completely symmetrical. I propose we add Future::join:

use async_std::future;

let a = future::ready(1);
let b = future::ready(2);
let pair = a.join(b);

assert_eq!(pair.await, (1, 2));

Future::try_join

The futures-preview library also exposes a try_join method. This is useful when you want to unwrap two results. Internally it uses TryFuture as a reference, which means this method should only exist on futures where Output = Result<T, E>, and I'm not entirely sure if that's feasible. However if it is it might be convenient to also expose:

use async_std::future;

let a = future::ready(Ok::<i32, i32>(1));
let b = future::ready(Ok::<i32, i32>(2));
let pair = a.try_join(b);

assert_eq!(pair.await, Ok((1, 2)));

Future::join_all

The third join combinator present is Future::join_all. The docs don't make a big sell on them (inefficient, set can't be modified after polling started, prefer futures_unordered), but it's probably still worth mentioning. I don't think we should add this combinator, but instead point people to use fold instead:

don't do this

use async_std::future::join_all;

async fn foo(i: u32) -> u32 { i }
let futures = vec![foo(1), foo(2), foo(3)];

assert_eq!(join_all(futures).await, [1, 2, 3]);

do this instead

let futures = vec![foo(1), foo(2), foo(3)];
let futures = futures.fold(|p, n| p.join(n))
assert_eq!(futures.await, [1, 2, 3]);

note: not tested this, but in general I don't think we need to worry about this case too much as handling the unordered case seems much more important and would cover this too.

This is somewhat tangential, but I wonder if the behavior of try_join!() is what it should be.

Currently, try_join!(a, b) will evaluate to Result<(A, B), E>.

But consider the fact that the now soft-deprecated macro try!() is equivalent to ?, so perhaps the try_ prefix should have the same effect as a ?.

What if try_join!(a, b) evaluated to (A, B) instead and returned the error if there was one? That would also mean one doesn't have to write ? after try_join!() because the ? is implied by the try_ part.

[yoshuawuyts]

Wrote more thoughts here: https://paper.dropbox.com/doc/2019-08-13-Fallible-Futures-Combinators--Aiz0YPhNHzntVEmJj~xUII2fAQ-001Bi7zqOMp6o5cyGuifL -- think this should cover most (and includes e.g. select).

[dignifiedquire]

is there a reason that join! can't handle both

let res: (_, _, _) = join!(ok(1), err(2), ok(3)).await;
let res: Vec<_> = join!(vec![ok(1), err(2), ok(3)]).await;

Where both would behave exactly the same, polling all features in parallel.

[skade]

Macros run before type checking, so this would be hard to to do in a way that allows for:

let vec = vec![ok(1), err(2), ok(3)];
join!(v);

[dignifiedquire]

so this would be hard to to do

you did not say impossible :)

[skade]

It's pretty much impossible.

[taiki-e]

This is somewhat tangential, but I wonder if the behavior of try_join!() is what it should be.

Currently, try_join!(a, b) will evaluate to Result<(A, B), E>.

But consider the fact that the now soft-deprecated macro try!() is equivalent to ?, so perhaps the try_ prefix should have the same effect as a ?.

What if try_join!(a, b) evaluated to (A, B) instead and returned the error if there was one? That would also mean one doesn't have to write ? after try_join!() because the ? is implied by the try_ part.

I think current behavior of try_join! is near to try_blocks.

[taiki-e]

Also, we (futures team) have designed these proc-macros to that they can be easily re-exported, so async-std can easily reuse them.

[skade]

We don't want to re-export futures types.

[taiki-e]

It is internal implementation of proc-macro, not a type.

[taiki-e]

It would be confusing if they use a different syntax than futures's select! macro because async-book also uses it.

[skade]

Using it would be an attempt at de-facto stabilizing it, though, as we're committing to our interface. Don't get me wrong, I don't think the futures-rs implementation is bad, just not committed stable

[skade]

FWIW, I see it as reasonable to recommend using the select macro for now (and potentially forever), but just not export it. We just don't have to commit to it now if we can't come up with a reliable design on our own.

[skade]

Coming back to join, I always found it jarring that the interface to join is a.join(b) and not (a,b).join(), is there a particular reason for this?

[yoshuawuyts]

Coming back to join, I always found it jarring that the interface to join is a.join(b) and not (a,b).join(), is there a particular reason for this?

This feels alien to me, and I don't know of any precedent in stdlib for this.