relentless 0.11.0

Composable retry policies for fallible operations and polling.
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

use crate::compat::Duration;
use core::fmt;

/// Why a retry loop terminated.
///
/// # Examples
///
/// ```
/// use relentless::{RetryPolicy, StopReason, stop};
///
/// let policy = RetryPolicy::new().stop(stop::attempts(1));
/// let (_result, stats) = policy
///     .retry(|_| Err::<(), _>("fail"))
///     .sleep(|_dur| {})
///     .with_stats()
///     .call();
///
/// assert_eq!(stats.stop_reason, StopReason::Exhausted);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum StopReason {
    /// The predicate accepted an `Ok` outcome — the retry loop succeeded and
    /// returned `Ok(T)`.
    Succeeded,
    /// The predicate accepted an `Err` outcome as terminal (did not request
    /// retry) — the loop returned [`RetryError::Rejected`](crate::RetryError::Rejected).
    Rejected,
    /// The stop strategy fired while the predicate still wanted to retry.
    Exhausted,
}

impl fmt::Display for StopReason {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            StopReason::Succeeded => f.write_str("succeeded"),
            StopReason::Rejected => f.write_str("rejected"),
            StopReason::Exhausted => f.write_str("retries exhausted"),
        }
    }
}

/// Aggregate statistics for a completed retry execution.
///
/// # Examples
///
/// ```
/// use relentless::{RetryPolicy, RetryStats, stop, wait};
/// use core::time::Duration;
///
/// let policy = RetryPolicy::new()
///     .stop(stop::attempts(3))
///     .wait(wait::fixed(Duration::from_millis(5)));
/// let (_result, stats): (Result<(), _>, RetryStats) = policy
///     .retry(|_| Err::<(), _>("fail"))
///     .sleep(|_dur| {})
///     .with_stats()
///     .call();
///
/// assert_eq!(stats.attempts, 3);
/// assert_eq!(stats.total_wait, Duration::from_millis(10));
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RetryStats {
    /// The total number of attempts executed.
    pub attempts: u32,
    /// Total wall-clock elapsed time, or `None` when no clock is available.
    pub total_elapsed: Option<Duration>,
    /// Cumulative duration requested from the wait strategy.
    pub total_wait: Duration,
    /// The reason the retry loop terminated.
    pub stop_reason: StopReason,
}