swansong 0.3.6

Graceful Shutdown
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
143
144
145
146
147
148
149

use super::guard::GuardInfo;
use std::{
    collections::BTreeMap,
    fmt::{self, Display, Formatter},
    panic::Location,
    sync::Arc,
    time::Duration,
};

/// A point-in-time snapshot of the outstanding [`Guard`][crate::Guard]s in a
/// [`Swansong`][crate::Swansong]'s subtree, aggregated by creation site.
///
/// Returned by [`Swansong::guard_report`][crate::Swansong::guard_report].
///
/// The [`Display`] implementation is suitable for logging when a shutdown
/// stalls on straggling guards:
///
/// ```text
/// 3 outstanding guards:
/// 2 × src/connection.rs:88:14 (oldest 42.3s)
/// 1 × src/tasks.rs:120:9 (oldest 3.1s)
/// ```
#[derive(Debug, Clone)]
pub struct GuardReport {
    entries: Vec<GuardReportEntry>,
}

/// The outstanding [`Guard`][crate::Guard]s that share a single creation site.
#[derive(Debug, Clone, Copy)]
pub struct GuardReportEntry {
    location: &'static Location<'static>,
    count: usize,
    oldest_age: Option<Duration>,
}

impl GuardReport {
    pub(crate) fn from_infos(infos: Vec<Arc<GuardInfo>>) -> Self {
        let mut by_location: BTreeMap<&'static Location<'static>, GuardReportEntry> =
            BTreeMap::new();
        for info in infos {
            let entry = by_location
                .entry(info.location())
                .or_insert_with(|| GuardReportEntry {
                    location: info.location(),
                    count: 0,
                    oldest_age: None,
                });
            entry.count += 1;
            entry.oldest_age = entry.oldest_age.max(info.age());
        }
        let mut entries: Vec<_> = by_location.into_values().collect();
        entries.sort_by(|a, b| {
            b.oldest_age
                .cmp(&a.oldest_age)
                .then_with(|| a.location.cmp(b.location))
        });
        Self { entries }
    }

    /// The total number of outstanding guards in this report.
    #[must_use]
    pub fn guard_count(&self) -> usize {
        self.entries.iter().map(GuardReportEntry::count).sum()
    }

    /// Whether there were no outstanding guards when this report was taken.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// The entries in this report, one per distinct creation site with at
    /// least one outstanding guard, sorted oldest-first.
    #[must_use]
    pub fn entries(&self) -> &[GuardReportEntry] {
        &self.entries
    }

    /// Iterate over the entries in this report, oldest-first.
    pub fn iter(&self) -> std::slice::Iter<'_, GuardReportEntry> {
        self.entries.iter()
    }
}

impl GuardReportEntry {
    /// The source location at which these guards were created, or from which
    /// they were cloned.
    #[must_use]
    pub fn location(&self) -> &'static Location<'static> {
        self.location
    }

    /// The number of outstanding guards created at this location.
    #[must_use]
    pub fn count(&self) -> usize {
        self.count
    }

    /// The age of the oldest outstanding guard created at this location.
    ///
    /// `None` when the system clock is unavailable, such as under miri.
    #[must_use]
    pub fn oldest_age(&self) -> Option<Duration> {
        self.oldest_age
    }
}

impl IntoIterator for GuardReport {
    type Item = GuardReportEntry;
    type IntoIter = std::vec::IntoIter<GuardReportEntry>;

    fn into_iter(self) -> Self::IntoIter {
        self.entries.into_iter()
    }
}

impl<'a> IntoIterator for &'a GuardReport {
    type Item = &'a GuardReportEntry;
    type IntoIter = std::slice::Iter<'a, GuardReportEntry>;

    fn into_iter(self) -> Self::IntoIter {
        self.entries.iter()
    }
}

impl Display for GuardReport {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        let count = self.guard_count();
        if count == 0 {
            return f.write_str("no outstanding guards");
        }
        let plural = if count == 1 { "" } else { "s" };
        write!(f, "{count} outstanding guard{plural}:")?;
        for entry in &self.entries {
            write!(f, "\n{entry}")?;
        }
        Ok(())
    }
}

impl Display for GuardReportEntry {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "{} × {}", self.count, self.location)?;
        if let Some(age) = self.oldest_age {
            write!(f, " (oldest {age:.1?})")?;
        }
        Ok(())
    }
}