taskvisor 0.4.0

Task supervisor for Tokio: restarts background tasks on failure with exponential backoff and jitter, graceful shutdown, and lifecycle events
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

//! # Restart policies.
//!
//! [`RestartPolicy`] decides whether a task is started again after an attempt finishes.
//!
//! It answers only the "restart or stop?" question. Retry delay is handled by [`BackoffPolicy`](crate::BackoffPolicy).
//!
//! | Policy                                  | On `Ok(())`                     | On retryable error        |
//! |-----------------------------------------|---------------------------------|---------------------------|
//! | [`Never`](RestartPolicy::Never)         | Stop                            | Stop                      |
//! | [`OnFailure`](RestartPolicy::OnFailure) | Stop                            | Restart with backoff      |
//! | [`Always`](RestartPolicy::Always)       | Restart after optional interval | Restart with backoff      |
//!
//! Fatal errors and cooperative cancellation stop the task for all policies.
//!
//! ## Choosing a policy
//!
//! - Use [`Never`](RestartPolicy::Never) for one-shot tasks.
//! - Use [`OnFailure`](RestartPolicy::OnFailure) for long-running workers.
//! - Use [`Always`](RestartPolicy::Always) for periodic tasks that finish and should run again.

/// Policy controlling whether a task is restarted after an attempt finishes.
///
/// This policy decides restart eligibility. Retry timing is controlled by [`BackoffPolicy`](crate::BackoffPolicy).
///
/// # Also
///
/// - [`BackoffPolicy`](crate::BackoffPolicy) - retry delays after failures
/// - [`TaskSpec`](crate::TaskSpec) - stores restart, backoff, timeout, and retry limit
#[derive(Clone, Copy, Debug)]
#[non_exhaustive]
pub enum RestartPolicy {
    /// Run once and never restart.
    ///
    /// The task stops after success, retryable error, fatal error, or cancellation.
    Never,
    /// Restart only after retryable failures.
    ///
    /// A successful completion stops the task. Fatal errors and cooperative
    /// cancellation also stop the task.
    OnFailure,
    /// Restart after success and after retryable failures.
    ///
    /// `interval` applies only after successful completions:
    /// - `Some(dur)` waits at least `dur` before the next run — but never less than the small
    ///   internal floor for an instantly-completing task, so a tiny or zero `dur` cannot hot-loop.
    /// - `None` restarts with no configured delay.
    ///
    /// Instantly-completing tasks are still rate-limited by a small internal floor to avoid a hot restart loop.
    ///
    /// Retryable failures ignore `interval` and use [`BackoffPolicy`](crate::BackoffPolicy).
    /// Fatal errors and cooperative cancellation stop the task.
    Always {
        /// Wait time between a successful completion and the next run.
        ///
        /// `None` means restart with no configured delay.
        interval: Option<std::time::Duration>,
    },
}

impl Default for RestartPolicy {
    /// Returns [`RestartPolicy::OnFailure`].
    fn default() -> Self {
        RestartPolicy::OnFailure
    }
}