backoff 0.4.0

Retry operations with exponential backoff policy.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

use std::thread;
use std::time::Duration;

use crate::backoff::Backoff;
use crate::error::Error;

/// Retries this operation according to the backoff policy.
/// backoff is reset before it is used.
///
/// # Examples
///
/// ```rust
/// # use backoff::{ExponentialBackoff, Error, retry};
/// let f = || -> Result<(), Error<&str>> {
///     // Business logic...
///     // Give up.
///     Err(Error::Permanent("error"))
/// };
///
/// let backoff = ExponentialBackoff::default();
/// let _ = retry(backoff, f).err().unwrap();
/// ```
pub fn retry<F, B, T, E>(backoff: B, op: F) -> Result<T, Error<E>>
where
    F: FnMut() -> Result<T, Error<E>>,
    B: Backoff,
{
    let mut retry = Retry {
        backoff,
        notify: NoopNotify,
        sleep: ThreadSleep,
    };

    retry.retry_notify(op)
}

/// Retries this operation according to the backoff policy.
/// Calls notify on failed attempts (in case of transient errors).
/// backoff is reset before it is used.
///
/// # Examples
///
/// ```rust
/// # use backoff::{Error, retry_notify};
/// # use backoff::backoff::Stop;
/// # use std::time::Duration;
/// let notify = |err, dur| { println!("Error happened at {:?}: {}", dur, err); };
/// let f = || -> Result<(), Error<&str>> {
///     // Business logic...
///     Err(Error::transient("error"))
/// };
///
/// let backoff = Stop{};
/// let _ = retry_notify(backoff, f, notify).err().unwrap();
/// ```
pub fn retry_notify<F, B, N, T, E>(backoff: B, op: F, notify: N) -> Result<T, Error<E>>
where
    F: FnMut() -> Result<T, Error<E>>,
    B: Backoff,
    N: Notify<E>,
{
    let mut retry = Retry {
        backoff,
        notify,
        sleep: ThreadSleep,
    };

    retry.retry_notify(op)
}

struct Retry<B, N, S> {
    backoff: B,
    notify: N,
    sleep: S,
}

impl<B, N, S> Retry<B, N, S> {
    pub fn retry_notify<F, T, E>(&mut self, mut op: F) -> Result<T, Error<E>>
    where
        F: FnMut() -> Result<T, Error<E>>,
        B: Backoff,
        N: Notify<E>,
        S: Sleep,
    {
        self.backoff.reset();

        loop {
            let err = match op() {
                Ok(v) => return Ok(v),
                Err(err) => err,
            };

            let (err, next) = match err {
                Error::Permanent(err) => return Err(Error::Permanent(err)),
                Error::Transient { err, retry_after } => {
                    match retry_after.or_else(|| self.backoff.next_backoff()) {
                        Some(next) => (err, next),
                        None => return Err(Error::transient(err)),
                    }
                }
            };

            self.notify.notify(err, next);

            self.sleep.sleep(next);
        }
    }
}

trait Sleep {
    fn sleep(&mut self, dur: Duration);
}

struct ThreadSleep;

impl Sleep for ThreadSleep {
    fn sleep(&mut self, dur: Duration) {
        thread::sleep(dur);
    }
}

/// Notify is called in [`retry_notify`](trait.Operation.html#method.retry_notify) in case of errors.
pub trait Notify<E> {
    fn notify(&mut self, err: E, duration: Duration);
}

impl<E, F> Notify<E> for F
where
    F: FnMut(E, Duration),
{
    fn notify(&mut self, err: E, duration: Duration) {
        self(err, duration)
    }
}

/// No-op implementation of [`Notify`]. Literally does nothing.
#[derive(Debug, Clone, Copy)]
pub struct NoopNotify;

impl<E> Notify<E> for NoopNotify {
    fn notify(&mut self, _: E, _: Duration) {}
}