Let's start with the using_recover() function:
- Any errors that have occurred within the future will be transformed into <Self as Future>::Item. Any <Self as Future>::Error type can be passed through, since we never produce an actual error.
- The futures::executor::block_on(F: Future) function will run a future until completion within the invoking thread. Any tasks within futures' default executor will also run on the invoking thread, but completion on the tasks may never occur since F may finish before the tasks have been completed. If this is the case, then the spawned tasks are dropped. LocalPool is often recommended for mitigating this issue, but for our examples block_on() will be sufficient.
All of these error handling functions can be found within the futures::FutureExt trait.
Now, onto our map_error() function:
- The <Self as Future>::map_err<E, F>(F: FnOnce(Self::Error) -> E) function will map a future's (Self) error into another error while returning a new future. This function is often used in conjunction with combinators, such as select or join, since we can guarantee that the futures will have the same error type to complete the composition.
Next, the err_into() function:
- Transforms the Self::Error into another Error type using the std::convert::Into trait
- Like futures::FutureExt::map_err, this function is useful for aggregating combinators together
The or_else() function:
- If <Self as Future> returns an error, futures::FutureExt::or_else will execute a closure with the following signature: FnOnce(Self::Error) -> futures::future::IntoFuture<Item = Self::Item>
- Useful for chaining failing combinators together
- The closure will not execute if the future has completed successfully, panics, or its future is dropped
Then the catch_unwind() function:
- This function is generally not recommended as a way to handle errors, and is only enabled with Rust's std option (which is enabled by default)
- Future traits implement the AssertUnwindSafe trait as AssertUnwindSafe<F: Future> trait
And lastly, the stream_panics() function:
- On line 95, this futures::StreamExt::catch_unwind function is similar to futures::FutureExt::catch_unwind
- If a panic occurs, it will be the last element of the stream for the stream
- This feature is only enabled with Rust's std option as well
- The AssertUnwindSafe trait is also implemented for streams as AssertUnwindSafe<S: Stream>
The combinators for streams are located in the futures::StreamExt trait, which has the same functions as futures::FutureExt with some additional stream-specific combinators such as split() and skip_while() that may prove to be useful for your projects.