//! Futures //! //! This module contains the `Future` trait and a number of adaptors for this //! trait. See the crate docs, and the docs for `Future`, for full detail. use core::fmt; use core::result; // Primitive futures mod empty; mod lazy; mod poll_fn; #[path = "result.rs"] mod result_; mod loop_fn; mod option; pub use self::empty::{empty, Empty}; pub use self::lazy::{lazy, Lazy}; pub use self::poll_fn::{poll_fn, PollFn}; pub use self::result_::{result, ok, err, FutureResult}; pub use self::loop_fn::{loop_fn, Loop, LoopFn}; #[doc(hidden)] #[deprecated(since = "0.1.4", note = "use `ok` instead")] #[cfg(feature = "with-deprecated")] pub use self::{ok as finished, Ok as Finished}; #[doc(hidden)] #[deprecated(since = "0.1.4", note = "use `err` instead")] #[cfg(feature = "with-deprecated")] pub use self::{err as failed, Err as Failed}; #[doc(hidden)] #[deprecated(since = "0.1.4", note = "use `result` instead")] #[cfg(feature = "with-deprecated")] pub use self::{result as done, FutureResult as Done}; #[doc(hidden)] #[deprecated(since = "0.1.7", note = "use `FutureResult` instead")] #[cfg(feature = "with-deprecated")] pub use self::{FutureResult as Ok}; #[doc(hidden)] #[deprecated(since = "0.1.7", note = "use `FutureResult` instead")] #[cfg(feature = "with-deprecated")] pub use self::{FutureResult as Err}; // combinators mod and_then; mod flatten; mod flatten_stream; mod fuse; mod into_stream; mod join; mod map; mod map_err; mod from_err; mod or_else; mod select; mod select2; mod then; mod either; mod inspect; // impl details mod chain; pub use self::and_then::AndThen; pub use self::flatten::Flatten; pub use self::flatten_stream::FlattenStream; pub use self::fuse::Fuse; pub use self::into_stream::IntoStream; pub use self::join::{Join, Join3, Join4, Join5}; pub use self::map::Map; pub use self::map_err::MapErr; pub use self::from_err::FromErr; pub use self::or_else::OrElse; pub use self::select::{Select, SelectNext}; pub use self::select2::Select2; pub use self::then::Then; pub use self::either::Either; pub use self::inspect::Inspect; if_std! { mod catch_unwind; mod join_all; mod select_all; mod select_ok; mod shared; pub use self::catch_unwind::CatchUnwind; pub use self::join_all::{join_all, JoinAll}; pub use self::select_all::{SelectAll, SelectAllNext, select_all}; pub use self::select_ok::{SelectOk, select_ok}; pub use self::shared::{Shared, SharedItem, SharedError}; #[doc(hidden)] #[deprecated(since = "0.1.4", note = "use join_all instead")] #[cfg(feature = "with-deprecated")] pub use self::join_all::join_all as collect; #[doc(hidden)] #[deprecated(since = "0.1.4", note = "use JoinAll instead")] #[cfg(feature = "with-deprecated")] pub use self::join_all::JoinAll as Collect; /// A type alias for `Box` #[doc(hidden)] #[deprecated(note = "removed without replacement, recommended to use a \ local extension trait or function if needed, more \ details in https://github.com/rust-lang-nursery/futures-rs/issues/228")] pub type BoxFuture = ::std::boxed::Box + Send>; impl Future for ::std::boxed::Box { type Item = F::Item; type Error = F::Error; fn poll(&mut self) -> Poll { (**self).poll() } } } use {Poll, stream}; /// Trait for types which are a placeholder of a value that may become /// available at some later point in time. /// /// In addition to the documentation here you can also find more information /// about futures [online] at [https://tokio.rs](https://tokio.rs) /// /// [online]: https://tokio.rs/docs/getting-started/futures/ /// /// Futures are used to provide a sentinel through which a value can be /// referenced. They crucially allow chaining and composing operations through /// consumption which allows expressing entire trees of computation as one /// sentinel value. /// /// The ergonomics and implementation of the `Future` trait are very similar to /// the `Iterator` trait in that there is just one methods you need /// to implement, but you get a whole lot of others for free as a result. /// /// # The `poll` method /// /// The core method of future, `poll`, is used to attempt to generate the value /// of a `Future`. This method *does not block* but is allowed to inform the /// caller that the value is not ready yet. Implementations of `poll` may /// themselves do work to generate the value, but it's guaranteed that this will /// never block the calling thread. /// /// A key aspect of this method is that if the value is not yet available the /// current task is scheduled to receive a notification when it's later ready to /// be made available. This follows what's typically known as a "readiness" or /// "pull" model where values are pulled out of futures on demand, and /// otherwise a task is notified when a value might be ready to get pulled out. /// /// The `poll` method is not intended to be called in general, but rather is /// typically called in the context of a "task" which drives a future to /// completion. For more information on this see the `task` module. /// /// More information about the details of `poll` and the nitty-gritty of tasks /// can be [found online at tokio.rs][poll-dox]. /// /// [poll-dox]: https://tokio.rs/docs/going-deeper-futures/futures-model/ /// /// # Combinators /// /// Like iterators, futures provide a large number of combinators to work with /// futures to express computations in a much more natural method than /// scheduling a number of callbacks. For example the `map` method can change /// a `Future` to a `Future` or an `and_then` combinator could /// create a future after the first one is done and only be resolved when the /// second is done. /// /// Combinators act very similarly to the methods on the `Iterator` trait itself /// or those on `Option` and `Result`. Like with iterators, the combinators are /// zero-cost and don't impose any extra layers of indirection you wouldn't /// otherwise have to write down. /// /// More information about combinators can be found [on tokio.rs]. /// /// [on tokio.rs]: https://tokio.rs/docs/going-deeper-futures/futures-mechanics/ #[must_use = "futures do nothing unless polled"] pub trait Future { /// The type of value that this future will resolved with if it is /// successful. type Item; /// The type of error that this future will resolve with if it fails in a /// normal fashion. type Error; /// Query this future to see if its value has become available, registering /// interest if it is not. /// /// This function will check the internal state of the future and assess /// whether the value is ready to be produced. Implementers of this function /// should ensure that a call to this **never blocks** as event loops may /// not work properly otherwise. /// /// When a future is not ready yet, the `Async::NotReady` value will be /// returned. In this situation the future will *also* register interest of /// the current task in the value being produced. This is done by calling /// `task::park` to retrieve a handle to the current `Task`. When the future /// is then ready to make progress (e.g. it should be `poll`ed again) the /// `unpark` method is called on the `Task`. /// /// More information about the details of `poll` and the nitty-gritty of /// tasks can be [found online at tokio.rs][poll-dox]. /// /// [poll-dox]: https://tokio.rs/docs/going-deeper-futures/futures-model/ /// /// # Runtime characteristics /// /// This function, `poll`, is the primary method for 'making progress' /// within a tree of futures. For example this method will be called /// repeatedly as the internal state machine makes its various transitions. /// Executors are responsible for ensuring that this function is called in /// the right location (e.g. always on an I/O thread or not). Unless it is /// otherwise arranged to be so, it should be ensured that **implementations /// of this function finish very quickly**. /// /// Returning quickly prevents unnecessarily clogging up threads and/or /// event loops while a `poll` function call, for example, takes up compute /// resources to perform some expensive computation. If it is known ahead /// of time that a call to `poll` may end up taking awhile, the work should /// be offloaded to a thread pool (or something similar) to ensure that /// `poll` can return quickly. /// /// Note that the `poll` function is not called repeatedly in a loop for /// futures typically, but only whenever the future itself is ready. If /// you're familiar with the `poll(2)` or `select(2)` syscalls on Unix /// it's worth noting that futures typically do *not* suffer the same /// problems of "all wakeups must poll all events". Futures have enough /// support for only polling futures which cause a wakeup. /// /// # Return value /// /// This function returns `Async::NotReady` if the future is not ready yet, /// `Err` if the future is finished but resolved to an error, or /// `Async::Ready` with the result of this future if it's finished /// successfully. Once a future has finished it is considered a contract /// error to continue polling the future. /// /// If `NotReady` is returned, then the future will internally register /// interest in the value being produced for the current task (through /// `task::park`). In other words, the current task will receive a /// notification (through the `unpark` method) once the value is ready to be /// produced or the future can make progress. /// /// Note that if `NotReady` is returned it only means that *this* task will /// receive a notification. Historical calls to `poll` with different tasks /// will not receive notifications. In other words, implementers of the /// `Future` trait need not store a queue of tasks to notify, but only the /// last task that called this method. Alternatively callers of this method /// can only rely on the most recent task which call `poll` being notified /// when a future is ready. /// /// # Panics /// /// Once a future has completed (returned `Ready` or `Err` from `poll`), /// then any future calls to `poll` may panic, block forever, or otherwise /// cause wrong behavior. The `Future` trait itself provides no guarantees /// about the behavior of `poll` after a future has completed. /// /// Callers who may call `poll` too many times may want to consider using /// the `fuse` adaptor which defines the behavior of `poll`, but comes with /// a little bit of extra cost. /// /// Additionally, calls to `poll` must always be made from within the /// context of a task. If a current task is not set then this method will /// likely panic. /// /// # Errors /// /// This future may have failed to finish the computation, in which case /// the `Err` variant will be returned with an appropriate payload of an /// error. fn poll(&mut self) -> Poll; /// Block the current thread until this future is resolved. /// /// This method will consume ownership of this future, driving it to /// completion via `poll` and blocking the current thread while it's waiting /// for the value to become available. Once the future is resolved the /// result of this future is returned. /// /// > **Note:** This method is not appropriate to call on event loops or /// > similar I/O situations because it will prevent the event /// > loop from making progress (this blocks the thread). This /// > method should only be called when it's guaranteed that the /// > blocking work associated with this future will be completed /// > by another thread. /// /// This method is only available when the `use_std` feature of this /// library is activated, and it is activated by default. /// /// # Panics /// /// This function does not attempt to catch panics. If the `poll` function /// of this future panics, panics will be propagated to the caller. #[cfg(feature = "use_std")] fn wait(self) -> result::Result where Self: Sized { ::executor::spawn(self).wait_future() } /// Convenience function for turning this future into a trait object which /// is also `Send`. /// /// This simply avoids the need to write `Box::new` and can often help with /// type inference as well by always returning a trait object. Note that /// this method requires the `Send` bound and returns a `BoxFuture`, which /// also encodes this. If you'd like to create a `Box` without the /// `Send` bound, then the `Box::new` function can be used instead. /// /// This method is only available when the `use_std` feature of this /// library is activated, and it is activated by default. /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future::{BoxFuture, result}; /// /// let a: BoxFuture = result(Ok(1)).boxed(); /// ``` #[cfg(feature = "use_std")] #[doc(hidden)] #[deprecated(note = "removed without replacement, recommended to use a \ local extension trait or function if needed, more \ details in https://github.com/rust-lang-nursery/futures-rs/issues/228")] #[allow(deprecated)] fn boxed(self) -> BoxFuture where Self: Sized + Send + 'static { ::std::boxed::Box::new(self) } /// Map this future's result 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. /// /// The closure provided will only be called if this future is resolved /// successfully. If this future returns an error, panics, or is dropped, /// then the closure provided will never be invoked. /// /// 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::prelude::*; /// use futures::future; /// /// let future = future::ok::(1); /// let new_future = future.map(|x| x + 3); /// assert_eq!(new_future.wait(), Ok(4)); /// ``` /// /// Calling `map` on an errored `Future` has no effect: /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let future = future::err::(1); /// let new_future = future.map(|x| x + 3); /// assert_eq!(new_future.wait(), Err(1)); /// ``` fn map(self, f: F) -> Map where F: FnOnce(Self::Item) -> U, Self: Sized, { assert_future::(map::new(self, f)) } /// Map this future's error to a different error, returning a new future. /// /// This function is similar to the `Result::map_err` where it will change /// the error type of the underlying future. This is useful for example to /// ensure that futures have the same error type when used with combinators /// like `select` and `join`. /// /// The closure provided will only be called if this future is resolved /// with an error. If this future returns a success, panics, or is /// dropped, then the closure provided will never be invoked. /// /// Note that this function consumes the receiving future and returns a /// wrapped version of it. /// /// # Examples /// /// ``` /// use futures::future::*; /// /// let future = err::(1); /// let new_future = future.map_err(|x| x + 3); /// assert_eq!(new_future.wait(), Err(4)); /// ``` /// /// Calling `map_err` on a successful `Future` has no effect: /// /// ``` /// use futures::future::*; /// /// let future = ok::(1); /// let new_future = future.map_err(|x| x + 3); /// assert_eq!(new_future.wait(), Ok(1)); /// ``` fn map_err(self, f: F) -> MapErr where F: FnOnce(Self::Error) -> E, Self: Sized, { assert_future::(map_err::new(self, f)) } /// Map this future's error to any error implementing `From` for /// this future's `Error`, returning a new future. /// /// This function does for futures what `try!` does for `Result`, /// by letting the compiler infer the type of the resulting error. /// Just as `map_err` above, this is useful for example to ensure /// that futures have the same error type when used with /// combinators like `select` and `join`. /// /// Note that this function consumes the receiving future and returns a /// wrapped version of it. /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let future_with_err_u8 = future::err::<(), u8>(1); /// let future_with_err_u32 = future_with_err_u8.from_err::(); /// ``` fn from_err>(self) -> FromErr where Self: Sized, { assert_future::(from_err::new(self)) } /// Chain on a computation for when a future finished, passing the result of /// the future to the provided closure `f`. /// /// This function can be used to ensure a computation runs regardless of /// the conclusion of the future. The closure provided will be yielded a /// `Result` once the future is complete. /// /// The returned value of the closure must implement the `IntoFuture` trait /// and can represent some more work to be done before the composed future /// is finished. Note that the `Result` type implements the `IntoFuture` /// trait so it is possible to simply alter the `Result` yielded to the /// closure and return it. /// /// If this future is dropped or panics then the closure `f` will not be /// run. /// /// Note that this function consumes the receiving future and returns a /// wrapped version of it. /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let future_of_1 = future::ok::(1); /// let future_of_4 = future_of_1.then(|x| { /// x.map(|y| y + 3) /// }); /// /// let future_of_err_1 = future::err::(1); /// let future_of_4 = future_of_err_1.then(|x| { /// match x { /// Ok(_) => panic!("expected an error"), /// Err(y) => future::ok::(y + 3), /// } /// }); /// ``` fn then(self, f: F) -> Then where F: FnOnce(result::Result) -> B, B: IntoFuture, Self: Sized, { assert_future::(then::new(self, f)) } /// Execute another future after this one has resolved successfully. /// /// This function can be used to chain two futures together and ensure that /// the final future isn't resolved until both have finished. The closure /// provided is yielded the successful result of this future and returns /// another value which can be converted into a future. /// /// Note that because `Result` implements the `IntoFuture` trait this method /// can also be useful for chaining fallible and serial computations onto /// the end of one future. /// /// If this future is dropped, panics, or completes with an error then the /// provided closure `f` is never called. /// /// Note that this function consumes the receiving future and returns a /// wrapped version of it. /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future::{self, FutureResult}; /// /// let future_of_1 = future::ok::(1); /// let future_of_4 = future_of_1.and_then(|x| { /// Ok(x + 3) /// }); /// /// let future_of_err_1 = future::err::(1); /// future_of_err_1.and_then(|_| -> FutureResult { /// panic!("should not be called in case of an error"); /// }); /// ``` fn and_then(self, f: F) -> AndThen where F: FnOnce(Self::Item) -> B, B: IntoFuture, Self: Sized, { assert_future::(and_then::new(self, f)) } /// Execute another future if this one resolves with an error. /// /// Return a future that passes along this future's value if it succeeds, /// and otherwise passes the error to the closure `f` and waits for the /// future it returns. The closure may also simply return a value that can /// be converted into a future. /// /// Note that because `Result` implements the `IntoFuture` trait this method /// can also be useful for chaining together fallback computations, where /// when one fails, the next is attempted. /// /// If this future is dropped, panics, or completes successfully then the /// provided closure `f` is never called. /// /// Note that this function consumes the receiving future and returns a /// wrapped version of it. /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future::{self, FutureResult}; /// /// let future_of_err_1 = future::err::(1); /// let future_of_4 = future_of_err_1.or_else(|x| -> Result { /// Ok(x + 3) /// }); /// /// let future_of_1 = future::ok::(1); /// future_of_1.or_else(|_| -> FutureResult { /// panic!("should not be called in case of success"); /// }); /// ``` fn or_else(self, f: F) -> OrElse where F: FnOnce(Self::Error) -> B, B: IntoFuture, Self: Sized, { assert_future::(or_else::new(self, f)) } /// Waits for either one of two futures to complete. /// /// This function will return a new future which awaits for either this or /// the `other` future to complete. The returned future will finish with /// both the value resolved and a future representing the completion of the /// other work. Both futures must have the same item and error type. /// /// Note that this function consumes the receiving futures and returns a /// wrapped version of them. /// /// # Examples /// /// ```no_run /// use futures::prelude::*; /// use futures::future; /// use std::thread; /// use std::time; /// /// let future1 = future::lazy(|| { /// thread::sleep(time::Duration::from_secs(5)); /// future::ok::('a') /// }); /// /// let future2 = future::lazy(|| { /// thread::sleep(time::Duration::from_secs(3)); /// future::ok::('b') /// }); /// /// let (value, last_future) = future1.select(future2).wait().ok().unwrap(); /// assert_eq!(value, 'a'); /// assert_eq!(last_future.wait().unwrap(), 'b'); /// ``` /// /// A poor-man's `join` implemented on top of `select`: /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// fn join(a: A, b: A) -> Box> /// where A: Future + 'static, /// { /// Box::new(a.select(b).then(|res| -> Box> { /// match res { /// Ok((a, b)) => Box::new(b.map(move |b| (a, b))), /// Err((a, _)) => Box::new(future::err(a)), /// } /// })) /// } /// ``` fn select(self, other: B) -> Select where B: IntoFuture, Self: Sized, { let f = select::new(self, other.into_future()); assert_future::<(Self::Item, SelectNext), (Self::Error, SelectNext), _>(f) } /// Waits for either one of two differently-typed futures to complete. /// /// This function will return a new future which awaits for either this or /// the `other` future to complete. The returned future will finish with /// both the value resolved and a future representing the completion of the /// other work. /// /// Note that this function consumes the receiving futures and returns a /// wrapped version of them. /// /// Also note that if both this and the second future have the same /// success/error type you can use the `Either::split` method to /// conveniently extract out the value at the end. /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future::{self, Either}; /// /// // A poor-man's join implemented on top of select2 /// /// fn join(a: A, b: B) -> Box> /// where A: Future + 'static, /// B: Future + 'static, /// E: 'static, /// { /// Box::new(a.select2(b).then(|res| -> Box> { /// match res { /// Ok(Either::A((x, b))) => Box::new(b.map(move |y| (x, y))), /// Ok(Either::B((y, a))) => Box::new(a.map(move |x| (x, y))), /// Err(Either::A((e, _))) => Box::new(future::err(e)), /// Err(Either::B((e, _))) => Box::new(future::err(e)), /// } /// })) /// } /// ``` fn select2(self, other: B) -> Select2 where B: IntoFuture, Self: Sized { select2::new(self, other.into_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. /// /// Both futures must have the same error type, and if either finishes with /// an error then the other will be dropped and that error will be /// returned. /// /// Note that this function consumes the receiving future and returns a /// wrapped version of it. /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let a = future::ok::(1); /// let b = future::ok::(2); /// let pair = a.join(b); /// /// assert_eq!(pair.wait(), Ok((1, 2))); /// ``` /// /// If one or both of the joined `Future`s is errored, the resulting /// `Future` will be errored: /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let a = future::ok::(1); /// let b = future::err::(2); /// let pair = a.join(b); /// /// assert_eq!(pair.wait(), Err(2)); /// ``` fn join(self, other: B) -> Join where B: IntoFuture, Self: Sized, { let f = join::new(self, other.into_future()); assert_future::<(Self::Item, B::Item), Self::Error, _>(f) } /// Same as `join`, but with more futures. fn join3(self, b: B, c: C) -> Join3 where B: IntoFuture, C: IntoFuture, Self: Sized, { join::new3(self, b.into_future(), c.into_future()) } /// Same as `join`, but with more futures. fn join4(self, b: B, c: C, d: D) -> Join4 where B: IntoFuture, C: IntoFuture, D: IntoFuture, Self: Sized, { join::new4(self, b.into_future(), c.into_future(), d.into_future()) } /// Same as `join`, but with more futures. fn join5(self, b: B, c: C, d: D, e: E) -> Join5 where B: IntoFuture, C: IntoFuture, D: IntoFuture, E: IntoFuture, Self: Sized, { join::new5(self, b.into_future(), c.into_future(), d.into_future(), e.into_future()) } /// 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::prelude::*; /// use futures::future; /// /// let future = future::ok::<_, bool>(17); /// let mut stream = future.into_stream(); /// assert_eq!(Ok(Async::Ready(Some(17))), stream.poll()); /// assert_eq!(Ok(Async::Ready(None)), stream.poll()); /// /// let future = future::err::(19); /// let mut stream = future.into_stream(); /// assert_eq!(Err(19), stream.poll()); /// assert_eq!(Ok(Async::Ready(None)), stream.poll()); /// ``` fn into_stream(self) -> IntoStream where Self: Sized { into_stream::new(self) } /// 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 /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let nested_future = future::ok::<_, u32>(future::ok::(1)); /// let future = nested_future.flatten(); /// assert_eq!(future.wait(), Ok(1)); /// ``` /// /// Calling `flatten` on an errored `Future`, or if the inner `Future` is /// errored, will result in an errored `Future`: /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let nested_future = future::ok::<_, u32>(future::err::(1)); /// let future = nested_future.flatten(); /// assert_eq!(future.wait(), Err(1)); /// ``` fn flatten(self) -> Flatten where Self::Item: IntoFuture, <::Item as IntoFuture>::Error: From<::Error>, Self: Sized { let f = flatten::new(self); assert_future::<<::Item as IntoFuture>::Item, <::Item as IntoFuture>::Error, _>(f) } /// 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::prelude::*; /// use futures::future; /// use futures::stream; /// /// let stream_items = vec![17, 18, 19]; /// let future_of_a_stream = future::ok::<_, bool>(stream::iter_ok(stream_items)); /// /// let stream = future_of_a_stream.flatten_stream(); /// /// let mut iter = stream.wait(); /// assert_eq!(Ok(17), iter.next().unwrap()); /// assert_eq!(Ok(18), iter.next().unwrap()); /// assert_eq!(Ok(19), iter.next().unwrap()); /// assert_eq!(None, iter.next()); /// ``` fn flatten_stream(self) -> FlattenStream where ::Item: stream::Stream, Self: Sized { flatten_stream::new(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 `NotReady` 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. /// /// # Examples /// /// ```rust /// use futures::prelude::*; /// use futures::future; /// /// let mut future = future::ok::(2); /// assert_eq!(future.poll(), Ok(Async::Ready(2))); /// /// // Normally, a call such as this would panic: /// //future.poll(); /// /// // This, however, is guaranteed to not panic /// let mut future = future::ok::(2).fuse(); /// assert_eq!(future.poll(), Ok(Async::Ready(2))); /// assert_eq!(future.poll(), Ok(Async::NotReady)); /// ``` fn fuse(self) -> Fuse where Self: Sized { let f = fuse::new(self); assert_future::(f) } /// Do something with the item of a future, 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. To do that, insert a call to inspect(). /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let future = future::ok::(1); /// let new_future = future.inspect(|&x| println!("about to resolve: {}", x)); /// assert_eq!(new_future.wait(), Ok(1)); /// ``` fn inspect(self, f: F) -> Inspect where F: FnOnce(&Self::Item) -> (), Self: Sized, { assert_future::(inspect::new(self, f)) } /// 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` where `F` implements `Future`. /// /// This method is only available when the `use_std` feature of this /// library is activated, and it is activated by default. /// /// # Examples /// /// ```rust /// use futures::prelude::*; /// use futures::future::{self, FutureResult}; /// /// let mut future = future::ok::(2); /// assert!(future.catch_unwind().wait().is_ok()); /// /// let mut future = future::lazy(|| -> FutureResult { /// panic!(); /// future::ok::(2) /// }); /// assert!(future.catch_unwind().wait().is_err()); /// ``` #[cfg(feature = "use_std")] fn catch_unwind(self) -> CatchUnwind where Self: Sized + ::std::panic::UnwindSafe { catch_unwind::new(self) } /// 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. /// /// The returned `Shared` future resolves successfully with /// `SharedItem` or erroneously with `SharedError`. /// Both `SharedItem` and `SharedError` implements `Deref` to allow shared /// access to the underlying result. Ownership of `Self::Item` and /// `Self::Error` cannot currently be reclaimed. /// /// This method is only available when the `use_std` feature of this /// library is activated, and it is activated by default. /// /// # Examples /// /// ``` /// use futures::prelude::*; /// use futures::future; /// /// let future = future::ok::<_, bool>(6); /// let shared1 = future.shared(); /// let shared2 = shared1.clone(); /// assert_eq!(6, *shared1.wait().unwrap()); /// assert_eq!(6, *shared2.wait().unwrap()); /// ``` /// /// ``` /// use std::thread; /// use futures::prelude::*; /// use futures::future; /// /// let future = future::ok::<_, bool>(6); /// let shared1 = future.shared(); /// let shared2 = shared1.clone(); /// let join_handle = thread::spawn(move || { /// assert_eq!(6, *shared2.wait().unwrap()); /// }); /// assert_eq!(6, *shared1.wait().unwrap()); /// join_handle.join().unwrap(); /// ``` #[cfg(feature = "use_std")] fn shared(self) -> Shared where Self: Sized { shared::new(self) } } impl<'a, F: ?Sized + Future> Future for &'a mut F { type Item = F::Item; type Error = F::Error; fn poll(&mut self) -> Poll { (**self).poll() } } // Just a helper function to ensure the futures we're returning all have the // right implementations. fn assert_future(t: F) -> F where F: Future, { t } /// Class of types which can be converted into a future. /// /// This trait is very similar to the `IntoIterator` trait and is intended to be /// used in a very similar fashion. pub trait IntoFuture { /// The future that this type can be converted into. type Future: Future; /// The item that the future may resolve with. type Item; /// The error that the future may resolve with. type Error; /// Consumes this object and produces a future. fn into_future(self) -> Self::Future; } impl IntoFuture for F { type Future = F; type Item = F::Item; type Error = F::Error; fn into_future(self) -> F { self } } impl IntoFuture for result::Result { type Future = FutureResult; type Item = T; type Error = E; fn into_future(self) -> FutureResult { result(self) } } /// Asynchronous conversion from a type `T`. /// /// This trait is analogous to `std::convert::From`, adapted to asynchronous /// computation. pub trait FutureFrom: Sized { /// The future for the conversion. type Future: Future; /// Possible errors during conversion. type Error; /// Consume the given value, beginning the conversion. fn future_from(T) -> Self::Future; } /// A trait for types which can spawn fresh futures. /// /// This trait is typically implemented for "executors", or those types which /// can execute futures to completion. Futures passed to `Spawn::spawn` /// typically get turned into a *task* and are then driven to completion. /// /// On spawn, the executor takes ownership of the future and becomes responsible /// to call `Future::poll()` whenever a readiness notification is raised. pub trait Executor> { /// Spawns a future to run on this `Executor`, typically in the /// "background". /// /// This function will return immediately, and schedule the future `future` /// to run on `self`. The details of scheduling and execution are left to /// the implementations of `Executor`, but this is typically a primary point /// for injecting concurrency in a futures-based system. Futures spawned /// through this `execute` function tend to run concurrently while they're /// waiting on events. /// /// # Errors /// /// Implementers of this trait are allowed to reject accepting this future /// as well. This can happen for various reason such as: /// /// * The executor is shut down /// * The executor has run out of capacity to execute futures /// /// The decision is left to the caller how to work with this form of error. /// The error returned transfers ownership of the future back to the caller. fn execute(&self, future: F) -> Result<(), ExecuteError>; } /// Errors returned from the `Spawn::spawn` function. pub struct ExecuteError { future: F, kind: ExecuteErrorKind, } /// Kinds of errors that can be returned from the `Execute::spawn` function. /// /// Executors which may not always be able to accept a future may return one of /// these errors, indicating why it was unable to spawn a future. #[derive(Debug, Copy, Clone, PartialEq)] pub enum ExecuteErrorKind { /// This executor has shut down and will no longer accept new futures to /// spawn. Shutdown, /// This executor has no more capacity to run more futures. Other futures /// need to finish before this executor can accept another. NoCapacity, #[doc(hidden)] __Nonexhaustive, } impl ExecuteError { /// Create a new `ExecuteError` pub fn new(kind: ExecuteErrorKind, future: F) -> ExecuteError { ExecuteError { future: future, kind: kind, } } /// Returns the associated reason for the error pub fn kind(&self) -> ExecuteErrorKind { self.kind } /// Consumes self and returns the original future that was spawned. pub fn into_future(self) -> F { self.future } } impl fmt::Debug for ExecuteError { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { match self.kind { ExecuteErrorKind::Shutdown => "executor has shut down".fmt(f), ExecuteErrorKind::NoCapacity => "executor has no more capacity".fmt(f), ExecuteErrorKind::__Nonexhaustive => panic!(), } } }