Trait futures_util::future::FutureExt
source · pub trait FutureExt: Future {
Show 14 methods
// Provided methods
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 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 { ... }
}
Expand description
An extension trait for Future
s that provides a variety of convenient
adapters.
Provided Methods§
sourcefn map<U, F>(self, f: F) -> Map<Self, F> ⓘ
fn map<U, F>(self, f: F) -> Map<Self, F> ⓘ
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);
sourcefn map_into<U>(self) -> MapInto<Self, U> ⓘ
fn map_into<U>(self) -> MapInto<Self, U> ⓘ
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.
sourcefn then<Fut, F>(self, f: F) -> Then<Self, Fut, F> ⓘ
fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F> ⓘ
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);
sourcefn left_future<B>(self) -> Either<Self, B> ⓘ
fn left_future<B>(self) -> Either<Self, B> ⓘ
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);
sourcefn right_future<A>(self) -> Either<A, Self> ⓘ
fn right_future<A>(self) -> Either<A, Self> ⓘ
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);
sourcefn into_stream(self) -> IntoStream<Self>where
Self: Sized,
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]);
sourcefn flatten(self) -> Flatten<Self> ⓘ
fn flatten(self) -> Flatten<Self> ⓘ
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);
sourcefn flatten_stream(self) -> FlattenStream<Self>
fn flatten_stream(self) -> FlattenStream<Self>
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]);
sourcefn fuse(self) -> Fuse<Self> ⓘwhere
Self: Sized,
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 fuse
d future is poll
ed 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.
sourcefn inspect<F>(self, f: F) -> Inspect<Self, F> ⓘ
fn inspect<F>(self, f: F) -> Inspect<Self, F> ⓘ
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);
sourcefn unit_error(self) -> UnitError<Self> ⓘwhere
Self: Sized,
fn unit_error(self) -> UnitError<Self> ⓘwhere
Self: Sized,
Turns a Future<Output = T>
into a
TryFuture<Ok = T, Error = ()
>.
sourcefn never_error(self) -> NeverError<Self> ⓘwhere
Self: Sized,
fn never_error(self) -> NeverError<Self> ⓘwhere
Self: Sized,
Turns a Future<Output = T>
into a
TryFuture<Ok = T, Error = Never
>.
sourcefn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>where
Self: Unpin,
fn poll_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Self::Output>where
Self: Unpin,
A convenience for calling Future::poll
on Unpin
future types.
sourcefn now_or_never(self) -> Option<Self::Output>where
Self: Sized,
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");