relentless 0.9.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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

//! Stop trait and built-in stop strategies.
//!
//! Stop strategies determine when the retry loop should give up. They compose
//! with `|` and `&` operators, or via `.or()` and `.and()` methods on the
//! [`Stop`] trait.

#[cfg(feature = "alloc")]
use crate::compat::Box;
use crate::state::RetryState;

mod composition;
mod strategies;

pub use composition::{StopAll, StopAny};
pub use strategies::{StopAfterAttempts, StopAfterElapsed, StopNever, attempts, elapsed, never};

/// Determines when the retry loop should stop.
///
/// Composition methods are provided directly on the trait with
/// `where Self: Sized` bounds, following the `Iterator` pattern.
///
/// # Examples
///
/// ```
/// use relentless::{RetryState, Stop};
///
/// struct StopAfterThree;
///
/// impl Stop for StopAfterThree {
///     fn should_stop(&self, state: &RetryState) -> bool {
///         const MAX_ATTEMPTS: u32 = 3;
///         state.attempt >= MAX_ATTEMPTS
///     }
/// }
/// ```
pub trait Stop {
    /// Returns `true` if the retry loop should stop given the current state.
    fn should_stop(&self, state: &RetryState) -> bool;

    /// Returns a strategy that stops when either side stops.
    ///
    /// This is the named equivalent of the `|` operator. Both sides are
    /// always evaluated (no short-circuit) so that stateful strategies
    /// receive every `should_stop` call.
    ///
    /// ```
    /// use relentless::{Stop, stop};
    /// use core::time::Duration;
    ///
    /// // These are equivalent:
    /// let a = stop::attempts(5).or(stop::elapsed(Duration::from_secs(2)));
    /// let b = stop::attempts(5) | stop::elapsed(Duration::from_secs(2));
    /// ```
    #[must_use]
    fn or<S: Stop>(self, other: S) -> StopAny<Self, S>
    where
        Self: Sized,
    {
        StopAny::new(self, other)
    }

    /// Returns a strategy that stops only when both sides stop.
    ///
    /// This is the named equivalent of the `&` operator. Both sides are
    /// always evaluated (no short-circuit) so that stateful strategies
    /// receive every `should_stop` call.
    ///
    /// ```
    /// use relentless::{Stop, stop};
    /// use core::time::Duration;
    ///
    /// // These are equivalent:
    /// let a = stop::attempts(5).and(stop::elapsed(Duration::from_secs(2)));
    /// let b = stop::attempts(5) & stop::elapsed(Duration::from_secs(2));
    /// ```
    #[must_use]
    fn and<S: Stop>(self, other: S) -> StopAll<Self, S>
    where
        Self: Sized,
    {
        StopAll::new(self, other)
    }
}

#[cfg(feature = "alloc")]
impl<S> Stop for Box<S>
where
    S: Stop + ?Sized,
{
    fn should_stop(&self, state: &RetryState) -> bool {
        (**self).should_stop(state)
    }
}