Function cancel_safe_futures::future::join_all_then_try

source · 
pub fn join_all_then_try<I>(iter: I) -> JoinAllThenTry<I::Item> ⓘ
where
    I: IntoIterator,
    I::Item: TryFuture,
Available on crate feature alloc only.
Expand description

Creates a future which represents either a collection of the results of the futures given or an error.

The returned future will drive execution for all of its underlying futures, collecting the results into a destination Vec<T> in the same order as they were provided.

Unlike futures::future::try_join_all, if any future returns an error then all other futures will not be canceled. Instead, all other futures will be run to completion.

  • If all futures complete successfully, then the returned future will succeed with a Vec of all the successful results.
  • If one or more futures fail, then the returned future will error out with the error for the first future listed that failed.

This function is only available when the std or alloc feature of this library is activated, and it is activated by default.

§Why use join_all_then_try?

See the documentation for join_then_try for a discussion of why you might want to use a then_try adapter.

§Notes

This adapter does not expose a way to gather and combine all returned errors. Implementing that is a future goal, but it requires some design work for a generic way to combine errors. To do that today, use futures::future::join_all and combine errors at the end.

§See Also

join_all_then_try will switch to the more powerful FuturesOrdered for performance reasons if the number of futures is large. You may want to look into using it or its counterpart FuturesUnordered directly.

Some examples for additional functionality provided by these are:

  • Adding new futures to the set even after it has been started.

  • Only polling the specific futures that have been woken. In cases where you have a lot of futures this will result in much more efficient polling.

§Examples

use futures_util::future;
use cancel_safe_futures::future::join_all_then_try;

let futures = vec![
    future::ok::<u32, u32>(1),
    future::ok::<u32, u32>(2),
    future::ok::<u32, u32>(3),
];

assert_eq!(join_all_then_try(futures).await, Ok(vec![1, 2, 3]));

let futures = vec![
    future::ok::<u32, u32>(1),
    future::err::<u32, u32>(2),
    future::ok::<u32, u32>(3),
];

assert_eq!(join_all_then_try(futures).await, Err(2));