Skip to main content

crumbkit_process/
escalation.rs

1//! The steps that stop a child: signals, each with a grace period, and then
2//! a kill.
3
4use std::time::Duration;
5
6use crate::Signal;
7
8#[cfg(test)]
9mod tests;
10
11/// How a run stops its child: each step sends a signal to the group and
12/// waits its grace for the child to exit, and a kill follows the last step.
13///
14/// The default escalation has no steps, so a stop kills at once. Each caller
15/// states its own steps, because a graceful signal helps only a child that
16/// handles it:
17///
18/// ```
19/// use std::time::Duration;
20///
21/// use crumbkit_process::{Escalation, Signal};
22///
23/// let polite = Escalation::default()
24///     .step(Signal::Interrupt, Duration::from_secs(2))
25///     .step(Signal::Terminate, Duration::from_secs(5));
26/// assert_ne!(polite, Escalation::default());
27/// ```
28///
29/// On Windows a stop skips the steps and ends the job at once (ADR-0171).
30#[derive(Clone, Debug, Default, PartialEq, Eq)]
31pub struct Escalation {
32    steps: Vec<(Signal, Duration)>,
33}
34
35impl Escalation {
36    /// Returns this escalation with one more step, which sends `signal` and
37    /// waits at most `grace` for the child to exit.
38    ///
39    /// A step after a [`Signal::Kill`] step runs only when the child has not
40    /// exited within the kill's grace.
41    #[must_use]
42    pub fn step(mut self, signal: Signal, grace: Duration) -> Self {
43        self.steps.push((signal, grace));
44        self
45    }
46
47    /// Returns the steps in order, each as its signal and its grace. The
48    /// kill that follows them is not a step.
49    pub(crate) fn steps(&self) -> impl Iterator<Item = (Signal, Duration)> + '_ {
50        self.steps.iter().copied()
51    }
52}