Trait futures_util::future::FutureExt

pub trait FutureExt: Future {
    fn map<U, F>(self, f: F) -> Map<Self, F>
    where
        F: FnOnce(Self::Output) -> U,
        Self: Sized,
    { ... }
    fn map_into<U>(self) -> MapInto<Self, U>
    where
        Self::Output: Into<U>,
        Self: Sized,
    { ... }
    fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F>
    where
        F: FnOnce(Self::Output) -> Fut,
        Fut: Future,
        Self: Sized,
    { ... }
    fn left_future<B>(self) -> Either<Self, B>
    where
        B: Future<Output = Self::Output>,
        Self: Sized,
    { ... }
    fn right_future<A>(self) -> Either<A, Self>
    where
        A: Future<Output = Self::Output>,
        Self: Sized,
    { ... }
    fn into_stream(self) -> IntoStream<Self>
    where
        Self: Sized,
    { ... }
    fn flatten(self) -> Flatten<Self>
    where
        Self::Output: Future,
        Self: Sized,
    { ... }
    fn flatten_stream(self) -> FlattenStream<Self>
    where
        Self::Output: Stream,
        Self: Sized,
    { ... }
    fn fuse(self) -> Fuse<Self>
    where
        Self: Sized,
    { ... }
    fn inspect<F>(self, f: F) -> Inspect<Self, F>
    where
        F: FnOnce(&Self::Output),
        Self: Sized,
    { ... }
    fn catch_unwind(self) -> CatchUnwind<Self>
    where
        Self: Sized + UnwindSafe,
    { ... }
    fn shared(self) -> Shared<Self>
    where
        Self: Sized,
        Self::Output: Clone,
    { ... }
    fn remote_handle(self) -> (Remote<Self>, RemoteHandle<Self::Output>)
    where
        Self: Sized,
    { ... }
    fn boxed<'a>(self) -> BoxFuture<'a, Self::Output>
    where
        Self: Sized + Send + 'a,
    { ... }
    fn boxed_local<'a>(self) -> LocalBoxFuture<'a, Self::Output>
    where
        Self: Sized + 'a,
    { ... }
    fn unit_error(self) -> UnitError<Self>
    where
        Self: Sized,
    { ... }
    fn never_error(self) -> NeverError<Self>
    where
        Self: Sized,
    { ... }
    fn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>
    where
        Self: Unpin,
    { ... }
    fn now_or_never(self) -> Option<Self::Output>
    where
        Self: Sized,
    { ... }
}

An extension trait for Futures that provides a variety of convenient adapters.

Provided methods

fn map<U, F>(self, f: F) -> Map<Self, F> where
    F: FnOnce(Self::Output) -> U,
    Self: Sized, 

Map this future’s output to a different type, returning a new future of the resulting type.

This function is similar to the Option::map or Iterator::map where it will change the type of the underlying future. This is useful to chain along a computation once a future has been resolved.

Note that this function consumes the receiving future and returns a wrapped version of it, similar to the existing map methods in the standard library.

Examples

use futures::future::FutureExt;

let future = async { 1 };
let new_future = future.map(|x| x + 3);
assert_eq!(new_future.await, 4);

fn map_into<U>(self) -> MapInto<Self, U> where
    Self::Output: Into<U>,
    Self: Sized, 

Map this future’s output to a different type, returning a new future of the resulting type.

This function is equivalent to calling map(Into::into) but allows naming the return type.

fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F> where
    F: FnOnce(Self::Output) -> Fut,
    Fut: Future,
    Self: Sized, 

Chain on a computation for when a future finished, passing the result of the future to the provided closure f.

The returned value of the closure must implement the Future trait and can represent some more work to be done before the composed future is finished.

The closure f is only run after successful completion of the self future.

Note that this function consumes the receiving future and returns a wrapped version of it.

Examples

use futures::future::FutureExt;

let future_of_1 = async { 1 };
let future_of_4 = future_of_1.then(|x| async move { x + 3 });
assert_eq!(future_of_4.await, 4);

fn left_future<B>(self) -> Either<Self, B> where
    B: Future<Output = Self::Output>,
    Self: Sized, 

Wrap this future in an Either future, making it the left-hand variant of that Either.

This can be used in combination with the right_future method to write if statements that evaluate to different futures in different branches.

Examples

use futures::future::FutureExt;

let x = 6;
let future = if x < 10 {
    async { true }.left_future()
} else {
    async { false }.right_future()
};

assert_eq!(future.await, true);

fn right_future<A>(self) -> Either<A, Self> where
    A: Future<Output = Self::Output>,
    Self: Sized, 

Wrap this future in an Either future, making it the right-hand variant of that Either.

This can be used in combination with the left_future method to write if statements that evaluate to different futures in different branches.

Examples

use futures::future::FutureExt;

let x = 6;
let future = if x > 10 {
    async { true }.left_future()
} else {
    async { false }.right_future()
};

assert_eq!(future.await, false);

fn into_stream(self) -> IntoStream<Self> where
    Self: Sized, 

Convert this future into a single element stream.

The returned stream contains single success if this future resolves to success or single error if this future resolves into error.

Examples

use futures::future::FutureExt;
use futures::stream::StreamExt;

let future = async { 17 };
let stream = future.into_stream();
let collected: Vec<_> = stream.collect().await;
assert_eq!(collected, vec![17]);

fn flatten(self) -> Flatten<Self> where
    Self::Output: Future,
    Self: Sized, 

Flatten the execution of this future when the output of this future is itself another future.

This can be useful when combining futures together to flatten the computation out the final result.

This method is roughly equivalent to self.then(|x| x).

Note that this function consumes the receiving future and returns a wrapped version of it.

Examples

use futures::future::FutureExt;

let nested_future = async { async { 1 } };
let future = nested_future.flatten();
assert_eq!(future.await, 1);

fn flatten_stream(self) -> FlattenStream<Self> where
    Self::Output: Stream,
    Self: Sized, 

Flatten the execution of this future when the successful result of this future is a stream.

This can be useful when stream initialization is deferred, and it is convenient to work with that stream as if stream was available at the call site.

Note that this function consumes this future and returns a wrapped version of it.

Examples

use futures::future::FutureExt;
use futures::stream::{self, StreamExt};

let stream_items = vec![17, 18, 19];
let future_of_a_stream = async { stream::iter(stream_items) };

let stream = future_of_a_stream.flatten_stream();
let list: Vec<_> = stream.collect().await;
assert_eq!(list, vec![17, 18, 19]);

fn fuse(self) -> Fuse<Self> where
    Self: Sized, 

Fuse a future such that poll will never again be called once it has completed. This method can be used to turn any Future into a FusedFuture.

Normally, once a future has returned Poll::Ready from poll, any further calls could exhibit bad behavior such as blocking forever, panicking, never returning, etc. If it is known that poll may be called too often then this method can be used to ensure that it has defined semantics.

If a fused future is polled after having returned Poll::Ready previously, it will return Poll::Pending, from poll again (and will continue to do so for all future calls to poll).

This combinator will drop the underlying future as soon as it has been completed to ensure resources are reclaimed as soon as possible.

fn inspect<F>(self, f: F) -> Inspect<Self, F> where
    F: FnOnce(&Self::Output),
    Self: Sized, 

Do something with the output of a future before passing it on.

When using futures, you’ll often chain several of them together. While working on such code, you might want to check out what’s happening at various parts in the pipeline, without consuming the intermediate value. To do that, insert a call to inspect.

Examples

use futures::future::FutureExt;

let future = async { 1 };
let new_future = future.inspect(|&x| println!("about to resolve: {}", x));
assert_eq!(new_future.await, 1);

fn catch_unwind(self) -> CatchUnwind<Self> where
    Self: Sized + UnwindSafe, 

Catches unwinding panics while polling the future.

In general, panics within a future can propagate all the way out to the task level. This combinator makes it possible to halt unwinding within the future itself. It’s most commonly used within task executors. It’s not recommended to use this for error handling.

Note that this method requires the UnwindSafe bound from the standard library. This isn’t always applied automatically, and the standard library provides an AssertUnwindSafe wrapper type to apply it after-the fact. To assist using this method, the Future trait is also implemented for AssertUnwindSafe<F> where F implements Future.

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

Examples

use futures::future::{self, FutureExt, Ready};

let future = future::ready(2);
assert!(future.catch_unwind().await.is_ok());

let future = future::lazy(|_| -> Ready<i32> {
    unimplemented!()
});
assert!(future.catch_unwind().await.is_err());

fn shared(self) -> Shared<Self> where
    Self: Sized,
    Self::Output: Clone, 

Create a cloneable handle to this future where all handles will resolve to the same result.

The shared combinator method provides a method to convert any future into a cloneable future. It enables a future to be polled by multiple threads.

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

Examples

use futures::future::FutureExt;

let future = async { 6 };
let shared1 = future.shared();
let shared2 = shared1.clone();

assert_eq!(6, shared1.await);
assert_eq!(6, shared2.await);

// Note, unlike most examples this is written in the context of a
// synchronous function to better illustrate the cross-thread aspect of
// the `shared` combinator.

use futures::future::FutureExt;
use futures::executor::block_on;
use std::thread;

let future = async { 6 };
let shared1 = future.shared();
let shared2 = shared1.clone();
let join_handle = thread::spawn(move || {
    assert_eq!(6, block_on(shared2));
});
assert_eq!(6, shared1.await);
join_handle.join().unwrap();

fn remote_handle(self) -> (Remote<Self>, RemoteHandle<Self::Output>) where
    Self: Sized, 

Turn this future into a future that yields () on completion and sends its output to another future on a separate task.

This can be used with spawning executors to easily retrieve the result of a future executing on a separate task or thread.

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

fn boxed<'a>(self) -> BoxFuture<'a, Self::Output> where
    Self: Sized + Send + 'a, 

Wrap the future in a Box, pinning it.

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

fn boxed_local<'a>(self) -> LocalBoxFuture<'a, Self::Output> where
    Self: Sized + 'a, 

Wrap the future in a Box, pinning it.

Similar to boxed, but without the Send requirement.

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

fn unit_error(self) -> UnitError<Self> where
    Self: Sized, 

Turns a Future<Output = T> into a TryFuture<Ok = T, Error = ()>.

fn never_error(self) -> NeverError<Self> where
    Self: Sized, 

Turns a Future<Output = T> into a TryFuture<Ok = T, Error = Never>.

fn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output> where
    Self: Unpin, 

A convenience for calling Future::poll on Unpin future types.

fn now_or_never(self) -> Option<Self::Output> where
    Self: Sized, 

Evaluates and consumes the future, returning the resulting output if the future is ready after the first call to Future::poll.

If poll instead returns Poll::Pending, None is returned.

This method is useful in cases where immediacy is more important than waiting for a result. It is also convenient for quickly obtaining the value of a future that is known to always resolve immediately.

Examples

use futures::{future::ready, future::pending};
let future_ready = ready("foobar");
let future_pending = pending::<&'static str>();

assert_eq!(future_ready.now_or_never(), Some("foobar"));
assert_eq!(future_pending.now_or_never(), None);

In cases where it is absolutely known that a future should always resolve immediately and never return Poll::Pending, this method can be combined with expect():

let future_ready = ready("foobar");

assert_eq!(future_ready.now_or_never().expect("Future not ready"), "foobar");

Implementors

impl<T: ?Sized> FutureExt for T where
    T: Future,