diff options
Diffstat (limited to 'third_party/rust/futures-0.1.31/src/future/mod.rs')
| -rw-r--r-- | third_party/rust/futures-0.1.31/src/future/mod.rs | 1171 |
1 files changed, 1171 insertions, 0 deletions
diff --git a/third_party/rust/futures-0.1.31/src/future/mod.rs b/third_party/rust/futures-0.1.31/src/future/mod.rs new file mode 100644 index 0000000000..9867765902 --- /dev/null +++ b/third_party/rust/futures-0.1.31/src/future/mod.rs @@ -0,0 +1,1171 @@ +//! 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<Future + Send>` + #[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<T, E> = ::std::boxed::Box<Future<Item = T, Error = E> + Send>; + + impl<F: ?Sized + Future> Future for ::std::boxed::Box<F> { + type Item = F::Item; + type Error = F::Error; + + fn poll(&mut self) -> Poll<Self::Item, Self::Error> { + (**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<Item=T>` to a `Future<Item=U>` 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<Self::Item, Self::Error>; + + /// 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<Self::Item, Self::Error> + 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<Future>` 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<i32, i32> = 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<Self::Item, Self::Error> + 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::<u32, u32>(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::<u32, u32>(1); + /// let new_future = future.map(|x| x + 3); + /// assert_eq!(new_future.wait(), Err(1)); + /// ``` + fn map<F, U>(self, f: F) -> Map<Self, F> + where F: FnOnce(Self::Item) -> U, + Self: Sized, + { + assert_future::<U, Self::Error, _>(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::<u32, u32>(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::<u32, u32>(1); + /// let new_future = future.map_err(|x| x + 3); + /// assert_eq!(new_future.wait(), Ok(1)); + /// ``` + fn map_err<F, E>(self, f: F) -> MapErr<Self, F> + where F: FnOnce(Self::Error) -> E, + Self: Sized, + { + assert_future::<Self::Item, E, _>(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::<u32>(); + /// ``` + fn from_err<E:From<Self::Error>>(self) -> FromErr<Self, E> + where Self: Sized, + { + assert_future::<Self::Item, E, _>(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::<u32, u32>(1); + /// let future_of_4 = future_of_1.then(|x| { + /// x.map(|y| y + 3) + /// }); + /// + /// let future_of_err_1 = future::err::<u32, u32>(1); + /// let future_of_4 = future_of_err_1.then(|x| { + /// match x { + /// Ok(_) => panic!("expected an error"), + /// Err(y) => future::ok::<u32, u32>(y + 3), + /// } + /// }); + /// ``` + fn then<F, B>(self, f: F) -> Then<Self, B, F> + where F: FnOnce(result::Result<Self::Item, Self::Error>) -> B, + B: IntoFuture, + Self: Sized, + { + assert_future::<B::Item, B::Error, _>(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::<u32, u32>(1); + /// let future_of_4 = future_of_1.and_then(|x| { + /// Ok(x + 3) + /// }); + /// + /// let future_of_err_1 = future::err::<u32, u32>(1); + /// future_of_err_1.and_then(|_| -> FutureResult<u32, u32> { + /// panic!("should not be called in case of an error"); + /// }); + /// ``` + fn and_then<F, B>(self, f: F) -> AndThen<Self, B, F> + where F: FnOnce(Self::Item) -> B, + B: IntoFuture<Error = Self::Error>, + Self: Sized, + { + assert_future::<B::Item, Self::Error, _>(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::<u32, u32>(1); + /// let future_of_4 = future_of_err_1.or_else(|x| -> Result<u32, u32> { + /// Ok(x + 3) + /// }); + /// + /// let future_of_1 = future::ok::<u32, u32>(1); + /// future_of_1.or_else(|_| -> FutureResult<u32, u32> { + /// panic!("should not be called in case of success"); + /// }); + /// ``` + fn or_else<F, B>(self, f: F) -> OrElse<Self, B, F> + where F: FnOnce(Self::Error) -> B, + B: IntoFuture<Item = Self::Item>, + Self: Sized, + { + assert_future::<Self::Item, B::Error, _>(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::<char, ()>('a') + /// }); + /// + /// let future2 = future::lazy(|| { + /// thread::sleep(time::Duration::from_secs(3)); + /// future::ok::<char, ()>('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: A, b: A) -> Box<Future<Item=(u32, u32), Error=u32>> + /// where A: Future<Item = u32, Error = u32> + 'static, + /// { + /// Box::new(a.select(b).then(|res| -> Box<Future<Item=_, Error=_>> { + /// match res { + /// Ok((a, b)) => Box::new(b.map(move |b| (a, b))), + /// Err((a, _)) => Box::new(future::err(a)), + /// } + /// })) + /// } + /// ``` + fn select<B>(self, other: B) -> Select<Self, B::Future> + where B: IntoFuture<Item=Self::Item, Error=Self::Error>, + Self: Sized, + { + let f = select::new(self, other.into_future()); + assert_future::<(Self::Item, SelectNext<Self, B::Future>), + (Self::Error, SelectNext<Self, B::Future>), _>(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, B, E>(a: A, b: B) -> Box<Future<Item=(A::Item, B::Item), Error=E>> + /// where A: Future<Error = E> + 'static, + /// B: Future<Error = E> + 'static, + /// E: 'static, + /// { + /// Box::new(a.select2(b).then(|res| -> Box<Future<Item=_, Error=_>> { + /// 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<B>(self, other: B) -> Select2<Self, B::Future> + 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::<u32, u32>(1); + /// let b = future::ok::<u32, u32>(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::<u32, u32>(1); + /// let b = future::err::<u32, u32>(2); + /// let pair = a.join(b); + /// + /// assert_eq!(pair.wait(), Err(2)); + /// ``` + fn join<B>(self, other: B) -> Join<Self, B::Future> + where B: IntoFuture<Error=Self::Error>, + 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<B, C>(self, b: B, c: C) -> Join3<Self, B::Future, C::Future> + where B: IntoFuture<Error=Self::Error>, + C: IntoFuture<Error=Self::Error>, + Self: Sized, + { + join::new3(self, b.into_future(), c.into_future()) + } + + /// Same as `join`, but with more futures. + fn join4<B, C, D>(self, b: B, c: C, d: D) + -> Join4<Self, B::Future, C::Future, D::Future> + where B: IntoFuture<Error=Self::Error>, + C: IntoFuture<Error=Self::Error>, + D: IntoFuture<Error=Self::Error>, + Self: Sized, + { + join::new4(self, b.into_future(), c.into_future(), d.into_future()) + } + + /// Same as `join`, but with more futures. + fn join5<B, C, D, E>(self, b: B, c: C, d: D, e: E) + -> Join5<Self, B::Future, C::Future, D::Future, E::Future> + where B: IntoFuture<Error=Self::Error>, + C: IntoFuture<Error=Self::Error>, + D: IntoFuture<Error=Self::Error>, + E: IntoFuture<Error=Self::Error>, + 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::<bool, _>(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<Self> + 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::<u32, u32>(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::<u32, u32>(1)); + /// let future = nested_future.flatten(); + /// assert_eq!(future.wait(), Err(1)); + /// ``` + fn flatten(self) -> Flatten<Self> + where Self::Item: IntoFuture, + <<Self as Future>::Item as IntoFuture>::Error: + From<<Self as Future>::Error>, + Self: Sized + { + let f = flatten::new(self); + assert_future::<<<Self as Future>::Item as IntoFuture>::Item, + <<Self as Future>::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<Self> + where <Self as Future>::Item: stream::Stream<Error=Self::Error>, + 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::<i32, u32>(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::<i32, u32>(2).fuse(); + /// assert_eq!(future.poll(), Ok(Async::Ready(2))); + /// assert_eq!(future.poll(), Ok(Async::NotReady)); + /// ``` + fn fuse(self) -> Fuse<Self> + where Self: Sized + { + let f = fuse::new(self); + assert_future::<Self::Item, Self::Error, _>(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::<u32, u32>(1); + /// let new_future = future.inspect(|&x| println!("about to resolve: {}", x)); + /// assert_eq!(new_future.wait(), Ok(1)); + /// ``` + fn inspect<F>(self, f: F) -> Inspect<Self, F> + where F: FnOnce(&Self::Item) -> (), + Self: Sized, + { + assert_future::<Self::Item, Self::Error, _>(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<F>` 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::<i32, u32>(2); + /// assert!(future.catch_unwind().wait().is_ok()); + /// + /// let mut future = future::lazy(|| -> FutureResult<i32, u32> { + /// panic!(); + /// future::ok::<i32, u32>(2) + /// }); + /// assert!(future.catch_unwind().wait().is_err()); + /// ``` + #[cfg(feature = "use_std")] + fn catch_unwind(self) -> CatchUnwind<Self> + 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<Self::Item>` or erroneously with `SharedError<Self::Error>`. + /// 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<Self> + 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::Item, Self::Error> { + (**self).poll() + } +} + +// Just a helper function to ensure the futures we're returning all have the +// right implementations. +fn assert_future<A, B, F>(t: F) -> F + where F: Future<Item=A, Error=B>, +{ + 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<Item=Self::Item, Error=Self::Error>; + + /// 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<F: Future> IntoFuture for F { + type Future = F; + type Item = F::Item; + type Error = F::Error; + + fn into_future(self) -> F { + self + } +} + +impl<T, E> IntoFuture for result::Result<T, E> { + type Future = FutureResult<T, E>; + type Item = T; + type Error = E; + + fn into_future(self) -> FutureResult<T, E> { + result(self) + } +} + +/// Asynchronous conversion from a type `T`. +/// +/// This trait is analogous to `std::convert::From`, adapted to asynchronous +/// computation. +pub trait FutureFrom<T>: Sized { + /// The future for the conversion. + type Future: Future<Item=Self, Error=Self::Error>; + + /// 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<F: Future<Item = (), Error = ()>> { + /// 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<F>>; +} + +/// Errors returned from the `Spawn::spawn` function. +pub struct ExecuteError<F> { + 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<F> ExecuteError<F> { + /// Create a new `ExecuteError` + pub fn new(kind: ExecuteErrorKind, future: F) -> ExecuteError<F> { + 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<F> fmt::Debug for ExecuteError<F> { + 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!(), + } + } +} |