Fix #19: Permit exiting early without more retries

This is important for many cases where only some cases are safe to
retry (e.g. non idempotent HTTP operations), or file system operations
where unknown errors are undefined behaviour.

Signed-off-by: Robert Collins <[email protected]>

Author: rbtcollins

src/lib.rs

@@ -2,14 +2,22 @@
 //!
 //! # Usage
 //!
-//! Retry an operation using the `retry` function. `retry` accepts an iterator over `Duration`s and
-//! a closure that returns a `Result`. The iterator is used to determine how long to wait after
-//! each unsuccessful try and how many times to try before giving up and returning `Result::Err`.
+//! Retry an operation using the `retry` function. `retry` accepts an iterator
+//! over `Duration`s and a closure that returns a `retry::OperationResult`. The
+//! iterator is used to determine how long to wait after each unsuccessful try
+//! and how many times to try before giving up and returning `Result::Err`. The
+//! closure is used to determine either the value to return, or whether to retry
+//! on non-fatal errors, or to immediately stop on fatal errors.
 //!
 //! Any type that implements `Iterator<Duration>` can be used to determine retry behavior, though a
 //! few useful implementations are provided in the `delay` module, including a fixed delay and
 //! exponential back-off.
 //!
+//! `retry::OperationResult` implements `From` for `std::result::Result`, so for
+//! the reasonably common case where no fatal errors are expected, just use
+//! `.into()` to cast into the required type - `Result::Err` becomes
+//! `OperationResult::Retry`.
+//!
 //! ```
 //! # use retry::retry;
 //! # use retry::delay::Fixed;
@@ -20,7 +28,7 @@
 //!         Some(n) if n == 3 => Ok("n is 3!"),
 //!         Some(_) => Err("n must be 3!"),
 //!         None => Err("n was never 3!"),
-//!     }
+//!     }.into()
 //! });
 //!
 //! assert!(result.is_ok());
@@ -39,7 +47,7 @@
 //!         Some(n) if n == 3 => Ok("n is 3!"),
 //!         Some(_) => Err("n must be 3!"),
 //!         None => Err("n was never 3!"),
-//!     }
+//!     }.into()
 //! });
 //!
 //! assert!(result.is_err());
@@ -58,11 +66,29 @@
 //!         Some(n) if n == 3 => Ok("n is 3!"),
 //!         Some(_) => Err("n must be 3!"),
 //!         None => Err("n was never 3!"),
-//!     }
+//!     }.into()
 //! });
 //!
 //! assert!(result.is_ok());
 //! ```
+//!
+//! To deal with fatal errors, return `OperationResult` directlythread::spawn(move || {
+//!
+//! ```
+//! # use retry::retry;
+//! # use retry::delay::Fixed;
+//! use retry::OperationResult;
+//! let mut collection = vec![1, 2].into_iter();
+//! let value = retry(Fixed::from_millis(1), || {
+//!     match collection.next() {
+//!         Some(n) if n == 2 => OperationResult::Ok(n),
+//!         Some(_) => OperationResult::Retry("not 2"),
+//!         None => OperationResult::Err("not found"),
+//!         }
+//!     }).unwrap();
+//!
+//! assert_eq!(value, 2);
+//! ```
 
 #![deny(missing_debug_implementations, missing_docs, warnings)]
 
@@ -74,22 +100,24 @@ use std::{
 };
 
 pub mod delay;
+pub mod opresult;
+
+pub use opresult::OperationResult;
 
 /// Retry the given operation synchronously until it succeeds, or until the given `Duration`
-/// iterator ends.
 pub fn retry<I, O, R, E>(iterable: I, mut operation: O) -> Result<R, Error<E>>
 where
     I: IntoIterator<Item = Duration>,
-    O: FnMut() -> Result<R, E>,
+    O: FnMut() -> OperationResult<R, E>,
 {
     let mut iterator = iterable.into_iter();
     let mut current_try = 1;
     let mut total_delay = Duration::default();
 
     loop {
         match operation() {
-            Ok(value) => return Ok(value),
-            Err(error) => {
+            OperationResult::Ok(value) => return Ok(value),
+            OperationResult::Retry(error) => {
                 if let Some(delay) = iterator.next() {
                     sleep(delay);
                     current_try += 1;
@@ -102,6 +130,13 @@ where
                     });
                 }
             }
+            OperationResult::Err(error) => {
+                return Err(Error::Operation {
+                    error: error,
+                    total_delay: total_delay,
+                    tries: current_try,
+                });
+            }
         }
     }
 }
@@ -158,16 +193,20 @@ mod tests {
     use std::time::Duration;
 
     use super::delay::{Exponential, Fixed, NoDelay, Range};
+    use super::opresult::OperationResult;
     use super::{retry, Error};
 
     #[test]
     fn succeeds_with_infinite_retries() {
         let mut collection = vec![1, 2, 3, 4, 5].into_iter();
 
-        let value = retry(NoDelay, || match collection.next() {
-            Some(n) if n == 5 => Ok(n),
-            Some(_) => Err("not 5"),
-            None => Err("not 5"),
+        let value = retry(NoDelay, || {
+            match collection.next() {
+                Some(n) if n == 5 => Ok(n),
+                Some(_) => Err("not 5"),
+                None => Err("not 5"),
+            }
+            .into()
         })
         .unwrap();
 
@@ -178,10 +217,13 @@ mod tests {
     fn succeeds_with_maximum_retries() {
         let mut collection = vec![1, 2].into_iter();
 
-        let value = retry(NoDelay.take(1), || match collection.next() {
-            Some(n) if n == 2 => Ok(n),
-            Some(_) => Err("not 2"),
-            None => Err("not 2"),
+        let value = retry(NoDelay.take(1), || {
+            match collection.next() {
+                Some(n) if n == 2 => Ok(n),
+                Some(_) => Err("not 2"),
+                None => Err("not 2"),
+            }
+            .into()
         })
         .unwrap();
 
@@ -192,10 +234,13 @@ mod tests {
     fn fails_after_last_try() {
         let mut collection = vec![1].into_iter();
 
-        let res = retry(NoDelay.take(1), || match collection.next() {
-            Some(n) if n == 2 => Ok(n),
-            Some(_) => Err("not 2"),
-            None => Err("not 2"),
+        let res = retry(NoDelay.take(1), || {
+            match collection.next() {
+                Some(n) if n == 2 => Ok(n),
+                Some(_) => Err("not 2"),
+                None => Err("not 2"),
+            }
+            .into()
         });
 
         assert_eq!(
@@ -208,14 +253,37 @@ mod tests {
         );
     }
 
+    #[test]
+    fn fatal_errors() {
+        let mut collection = vec![1].into_iter();
+
+        let res = retry(NoDelay.take(2), || match collection.next() {
+            Some(n) if n == 2 => OperationResult::Ok(n),
+            Some(_) => OperationResult::Err("no retry"),
+            None => OperationResult::Err("not 2"),
+        });
+
+        assert_eq!(
+            res,
+            Err(Error::Operation {
+                error: "no retry",
+                tries: 1,
+                total_delay: Duration::from_millis(0)
+            })
+        );
+    }
+
     #[test]
     fn succeeds_with_fixed_delay() {
         let mut collection = vec![1, 2].into_iter();
 
-        let value = retry(Fixed::from_millis(1), || match collection.next() {
-            Some(n) if n == 2 => Ok(n),
-            Some(_) => Err("not 2"),
-            None => Err("not 2"),
+        let value = retry(Fixed::from_millis(1), || {
+            match collection.next() {
+                Some(n) if n == 2 => Ok(n),
+                Some(_) => Err("not 2"),
+                None => Err("not 2"),
+            }
+            .into()
         })
         .unwrap();
 
@@ -226,10 +294,13 @@ mod tests {
     fn succeeds_with_exponential_delay() {
         let mut collection = vec![1, 2].into_iter();
 
-        let value = retry(Exponential::from_millis(1), || match collection.next() {
-            Some(n) if n == 2 => Ok(n),
-            Some(_) => Err("not 2"),
-            None => Err("not 2"),
+        let value = retry(Exponential::from_millis(1), || {
+            match collection.next() {
+                Some(n) if n == 2 => Ok(n),
+                Some(_) => Err("not 2"),
+                None => Err("not 2"),
+            }
+            .into()
         })
         .unwrap();
 
@@ -240,10 +311,13 @@ mod tests {
     fn succeeds_with_ranged_delay() {
         let mut collection = vec![1, 2].into_iter();
 
-        let value = retry(Range::from_millis_exclusive(1, 10), || match collection.next() {
-            Some(n) if n == 2 => Ok(n),
-            Some(_) => Err("not 2"),
-            None => Err("not 2"),
+        let value = retry(Range::from_millis_exclusive(1, 10), || {
+            match collection.next() {
+                Some(n) if n == 2 => Ok(n),
+                Some(_) => Err("not 2"),
+                None => Err("not 2"),
+            }
+            .into()
         })
         .unwrap();
 

src/opresult.rs

@@ -0,0 +1,49 @@
+//! Provides a ternary result for operations
+//!
+//! # Examples
+//!
+//! ```rust
+//! # use retry::retry;
+//! # use retry::delay::Fixed;
+//! use retry::OperationResult;
+//! let mut collection = vec![1, 2].into_iter();
+//! let value = retry(Fixed::from_millis(1), || {
+//!     match collection.next() {
+//!         Some(n) if n == 2 => OperationResult::Ok(n),
+//!         Some(_) => OperationResult::Retry("not 2"),
+//!         None => OperationResult::Err("not found"),
+//!         }
+//!     }).unwrap();
+//!
+//! assert_eq!(value, 2);
+//! ```
+
+/// `OperationResult` is a type that represents either success ([`Ok`]) or
+/// failure ([`Err`]) or possible failure that should be retried ([`Retry`]).
+#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
+pub enum OperationResult<T, E> {
+    /// Contains the success value
+    Ok(T),
+    /// Contains the error value if duration is exceeded
+    Retry(E),
+    /// Contains an immediate error value
+    Err(E),
+}
+
+impl<T, E> From<Result<T, E>> for OperationResult<T, E> {
+    fn from(item: Result<T, E>) -> Self {
+        match item {
+            Ok(v) => OperationResult::Ok(v),
+            Err(e) => OperationResult::Retry(e),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    // use std::time::Duration;
+
+    // use super::{Error, retry};
+    // use super::delay::{Exponential, Fixed, NoDelay, Range};
+    // use super::opresult::OperationResult;
+}