[−][src]Trait futures::prelude::FutureExt
An extension trait for Future
s 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,
F: FnOnce(Self::Output) -> U,
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
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let future = future::ready(1); let new_future = future.map(|x| x + 3); assert_eq!(await!(new_future), 4);
fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F> where
F: FnOnce(Self::Output) -> Fut,
Fut: Future,
F: FnOnce(Self::Output) -> Fut,
Fut: Future,
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
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let future_of_1 = future::ready(1); let future_of_4 = future_of_1.then(|x| future::ready(x + 3)); assert_eq!(await!(future_of_4), 4);
fn join<Fut2>(self, other: Fut2) -> Join<Self, Fut2> where
Fut2: Future,
Fut2: Future,
Joins the result of two futures, waiting for them both to complete.
This function will return a new future which awaits both this and the
other
future to complete. The returned future will finish with a tuple
of both results.
Note that this function consumes the receiving future and returns a wrapped version of it.
Examples
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let a = future::ready(1); let b = future::ready(2); let pair = a.join(b); assert_eq!(await!(pair), (1, 2));
fn join3<Fut2, Fut3>(
self,
future2: Fut2,
future3: Fut3
) -> Join3<Self, Fut2, Fut3> where
Fut2: Future,
Fut3: Future,
self,
future2: Fut2,
future3: Fut3
) -> Join3<Self, Fut2, Fut3> where
Fut2: Future,
Fut3: Future,
Same as join
, but with more futures.
Examples
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let a = future::ready(1); let b = future::ready(2); let c = future::ready(3); let tuple = a.join3(b, c); assert_eq!(await!(tuple), (1, 2, 3));
fn join4<Fut2, Fut3, Fut4>(
self,
future2: Fut2,
future3: Fut3,
future4: Fut4
) -> Join4<Self, Fut2, Fut3, Fut4> where
Fut2: Future,
Fut3: Future + Future,
Fut4: Future,
self,
future2: Fut2,
future3: Fut3,
future4: Fut4
) -> Join4<Self, Fut2, Fut3, Fut4> where
Fut2: Future,
Fut3: Future + Future,
Fut4: Future,
Same as join
, but with more futures.
Examples
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let a = future::ready(1); let b = future::ready(2); let c = future::ready(3); let d = future::ready(4); let tuple = a.join4(b, c, d); assert_eq!(await!(tuple), (1, 2, 3, 4));
fn join5<Fut2, Fut3, Fut4, Fut5>(
self,
future2: Fut2,
future3: Fut3,
future4: Fut4,
future5: Fut5
) -> Join5<Self, Fut2, Fut3, Fut4, Fut5> where
Fut2: Future,
Fut3: Future + Future,
Fut4: Future,
Fut5: Future,
self,
future2: Fut2,
future3: Fut3,
future4: Fut4,
future5: Fut5
) -> Join5<Self, Fut2, Fut3, Fut4, Fut5> where
Fut2: Future,
Fut3: Future + Future,
Fut4: Future,
Fut5: Future,
Same as join
, but with more futures.
Examples
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let a = future::ready(1); let b = future::ready(2); let c = future::ready(3); let d = future::ready(4); let e = future::ready(5); let tuple = a.join5(b, c, d, e); assert_eq!(await!(tuple), (1, 2, 3, 4, 5));
fn into_stream(self) -> IntoStream<Self>
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
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; use futures::stream::StreamExt; let future = future::ready(17); let stream = future.into_stream(); let collected: Vec<_> = await!(stream.collect()); assert_eq!(collected, vec![17]);
fn flatten(self) -> Flatten<Self> where
Self::Output: Future,
Self::Output: Future,
Flatten the execution of this future when the successful result 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 can only be called
when the successful result of this future itself implements the
IntoFuture
trait and the error can be created from this future's error
type.
This method is roughly equivalent to self.and_then(|x| x)
.
Note that this function consumes the receiving future and returns a wrapped version of it.
Examples
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let nested_future = future::ready(future::ready(1)); let future = nested_future.flatten(); assert_eq!(await!(future), 1);
fn flatten_stream(self) -> FlattenStream<Self> where
Self::Output: Stream,
Self::Output: Stream,
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
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; use futures::stream::{self, StreamExt}; let stream_items = vec![17, 18, 19]; let future_of_a_stream = future::ready(stream::iter(stream_items)); let stream = future_of_a_stream.flatten_stream(); let list: Vec<_> = await!(stream.collect()); assert_eq!(list, vec![17, 18, 19]);
fn fuse(self) -> Fuse<Self>
Fuse a future such that poll
will never again be called once it has
completed.
Currently once a future has returned Ready
or Err
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.
Once a future has been fuse
d and it returns a completion from poll
,
then it will forever return Pending
from poll
again (never
resolve). This, unlike the trait's poll
method, is guaranteed.
This combinator will drop this future as soon as it's 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),
F: FnOnce(&Self::Output),
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
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let future = future::ready(1); let new_future = future.inspect(|&x| println!("about to resolve: {}", x)); assert_eq!(await!(new_future), 1);
fn catch_unwind(self) -> CatchUnwind<Self> where
Self: UnwindSafe,
Self: 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
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt, Ready}; let mut future = future::ready(2); assert!(await!(future.catch_unwind()).is_ok()); let mut future = future::lazy(|_| -> Ready<i32> { unimplemented!() }); assert!(await!(future.catch_unwind()).is_err());
Create a cloneable handle to this future where all handles will resolve to the same result.
The shared() 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
#![feature(async_await, await_macro, futures_api)] use futures::future::{self, FutureExt}; let future = future::ready(6); let shared1 = future.shared(); let shared2 = shared1.clone(); assert_eq!(6, await!(shared1)); assert_eq!(6, await!(shared2));
// 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::{self, FutureExt}; use futures::executor::block_on; use std::thread; let future = future::ready(6); let shared1 = future.shared(); let shared2 = shared1.clone(); let join_handle = thread::spawn(move || { assert_eq!(6, block_on(shared2)); }); assert_eq!(6, block_on(shared1)); join_handle.join().unwrap();
fn remote_handle(self) -> (Remote<Self>, RemoteHandle<Self::Output>)
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.
fn boxed(self) -> Pin<Box<Self>>
Wrap the future in a Box, pinning it.
fn unit_error(self) -> UnitError<Self>
Turns a Future
into a TryFuture
with Error = ()
.
fn poll_unpin(&mut self, lw: &LocalWaker) -> Poll<Self::Output> where
Self: Unpin,
Self: Unpin,
A convenience for calling Future::poll
on Unpin
future types.
Implementors
impl<T> FutureExt for T where
T: Future + ?Sized,
[src]
impl<T> FutureExt for T where
T: Future + ?Sized,
fn map<U, F>(self, f: F) -> Map<Self, F> where
F: FnOnce(Self::Output) -> U,
[src]
fn map<U, F>(self, f: F) -> Map<Self, F> where
F: FnOnce(Self::Output) -> U,
fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F> where
F: FnOnce(Self::Output) -> Fut,
Fut: Future,
[src]
fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F> where
F: FnOnce(Self::Output) -> Fut,
Fut: Future,
fn join<Fut2>(self, other: Fut2) -> Join<Self, Fut2> where
Fut2: Future,
[src]
fn join<Fut2>(self, other: Fut2) -> Join<Self, Fut2> where
Fut2: Future,
fn join3<Fut2, Fut3>(
self,
future2: Fut2,
future3: Fut3
) -> Join3<Self, Fut2, Fut3> where
Fut2: Future,
Fut3: Future,
[src]
fn join3<Fut2, Fut3>(
self,
future2: Fut2,
future3: Fut3
) -> Join3<Self, Fut2, Fut3> where
Fut2: Future,
Fut3: Future,
fn join4<Fut2, Fut3, Fut4>(
self,
future2: Fut2,
future3: Fut3,
future4: Fut4
) -> Join4<Self, Fut2, Fut3, Fut4> where
Fut2: Future,
Fut3: Future + Future,
Fut4: Future,
[src]
fn join4<Fut2, Fut3, Fut4>(
self,
future2: Fut2,
future3: Fut3,
future4: Fut4
) -> Join4<Self, Fut2, Fut3, Fut4> where
Fut2: Future,
Fut3: Future + Future,
Fut4: Future,
fn join5<Fut2, Fut3, Fut4, Fut5>(
self,
future2: Fut2,
future3: Fut3,
future4: Fut4,
future5: Fut5
) -> Join5<Self, Fut2, Fut3, Fut4, Fut5> where
Fut2: Future,
Fut3: Future + Future,
Fut4: Future,
Fut5: Future,
[src]
fn join5<Fut2, Fut3, Fut4, Fut5>(
self,
future2: Fut2,
future3: Fut3,
future4: Fut4,
future5: Fut5
) -> Join5<Self, Fut2, Fut3, Fut4, Fut5> where
Fut2: Future,
Fut3: Future + Future,
Fut4: Future,
Fut5: Future,
fn into_stream(self) -> IntoStream<Self>
[src]
fn into_stream(self) -> IntoStream<Self>
fn flatten(self) -> Flatten<Self> where
Self::Output: Future,
[src]
fn flatten(self) -> Flatten<Self> where
Self::Output: Future,
fn flatten_stream(self) -> FlattenStream<Self> where
Self::Output: Stream,
[src]
fn flatten_stream(self) -> FlattenStream<Self> where
Self::Output: Stream,
fn fuse(self) -> Fuse<Self>
[src]
fn fuse(self) -> Fuse<Self>
fn inspect<F>(self, f: F) -> Inspect<Self, F> where
F: FnOnce(&Self::Output),
[src]
fn inspect<F>(self, f: F) -> Inspect<Self, F> where
F: FnOnce(&Self::Output),
fn catch_unwind(self) -> CatchUnwind<Self> where
Self: UnwindSafe,
[src]
fn catch_unwind(self) -> CatchUnwind<Self> where
Self: UnwindSafe,
fn remote_handle(self) -> (Remote<Self>, RemoteHandle<Self::Output>)
[src]
fn remote_handle(self) -> (Remote<Self>, RemoteHandle<Self::Output>)
fn boxed(self) -> Pin<Box<Self>>
[src]
fn boxed(self) -> Pin<Box<Self>>
fn unit_error(self) -> UnitError<Self>
[src]
fn unit_error(self) -> UnitError<Self>
fn poll_unpin(&mut self, lw: &LocalWaker) -> Poll<Self::Output> where
Self: Unpin,
[src]
fn poll_unpin(&mut self, lw: &LocalWaker) -> Poll<Self::Output> where
Self: Unpin,