Skip to main content

subc_control/
subtree.rs

1use serde::{Deserialize, Serialize};
2
3open_string_enum! {
4    /// The measurement behind a module's memory including child processes.
5    #[non_exhaustive]
6    SubtreeSource {
7        CgroupMemory => "cgroup_memory",
8        ProcessSum => "process_sum",
9        Unavailable => "unavailable"
10    }
11}
12
13/// A report-only memory reading of a module's process container.
14///
15/// Use the constructors rather than struct literals so new fields stay additive.
16#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
17#[non_exhaustive]
18pub struct SubtreeReading {
19    pub source: SubtreeSource,
20    #[serde(default, skip_serializing_if = "Option::is_none")]
21    pub memory_bytes: Option<u64>,
22    /// Absent means swap is not accounted, not zero.
23    #[serde(default, skip_serializing_if = "Option::is_none")]
24    pub swap_bytes: Option<u64>,
25    #[serde(default, skip_serializing_if = "Option::is_none")]
26    pub process_count: Option<u64>,
27    #[serde(default, skip_serializing_if = "Option::is_none")]
28    pub reason: Option<String>,
29}
30
31impl SubtreeReading {
32    /// Cgroup charges, including page cache, rather than summed resident sets.
33    pub fn cgroup_memory(memory_bytes: u64, swap_bytes: Option<u64>, process_count: u64) -> Self {
34        Self {
35            source: SubtreeSource::CgroupMemory,
36            memory_bytes: Some(memory_bytes),
37            swap_bytes,
38            process_count: Some(process_count),
39            reason: None,
40        }
41    }
42
43    /// Sum of process resident sets. Shared pages count once per process.
44    pub fn process_sum(memory_bytes: u64, swap_bytes: Option<u64>, process_count: u64) -> Self {
45        Self {
46            source: SubtreeSource::ProcessSum,
47            memory_bytes: Some(memory_bytes),
48            swap_bytes,
49            process_count: Some(process_count),
50            reason: None,
51        }
52    }
53
54    /// No container-wide figure could be obtained; never substitutes a PID reading.
55    pub fn unavailable(reason: impl Into<String>) -> Self {
56        Self {
57            source: SubtreeSource::Unavailable,
58            memory_bytes: None,
59            swap_bytes: None,
60            process_count: None,
61            reason: Some(reason.into()),
62        }
63    }
64}
65
66#[cfg(test)]
67mod tests {
68    use crate::{SubtreeReading, SupervisorEntry, SupervisorHealthStatus};
69
70    #[test]
71    fn absent_subtree_preserves_exact_list_entry_bytes() {
72        let entry =
73            SupervisorEntry::new("m", "running", true, true, SupervisorHealthStatus::Unknown);
74        assert_eq!(
75            serde_json::to_string(&entry).unwrap(),
76            r#"{"module_id":"m","state":"running","enabled":true,"live":true,"protocol":"subc","health":"unknown","last_probe_ms":null}"#
77        );
78    }
79
80    #[test]
81    fn cgroup_swap_absence_is_omitted_not_zero() {
82        let reading = SubtreeReading::cgroup_memory(8192, None, 3);
83        assert_eq!(
84            serde_json::to_value(reading).unwrap(),
85            serde_json::json!({
86                "source": "cgroup_memory", "memory_bytes": 8192, "process_count": 3
87            })
88        );
89    }
90
91    #[test]
92    fn older_entry_decoder_ignores_tree() {
93        #[derive(serde::Deserialize)]
94        struct LegacyEntry {
95            module_id: String,
96        }
97        let entry =
98            SupervisorEntry::new("m", "running", true, true, SupervisorHealthStatus::Unknown)
99                .with_tree(Some(crate::TreeReading {
100                    measured_at_ms: Some(1_800_000_000_123),
101                    own: None,
102                    bound: None,
103                    cpu_ms: 1,
104                    memory_bytes: 4096,
105                    memory_kind: crate::ChildMemoryKind::ResidentSet,
106                    process_count: 3,
107                    source: crate::TreeSource::ProcessTree,
108                    groups: Vec::new(),
109                }));
110        let bytes = serde_json::to_vec(&entry).unwrap();
111        let old: LegacyEntry = serde_json::from_slice(&bytes).unwrap();
112        assert_eq!(old.module_id, "m");
113        assert!(!String::from_utf8(bytes).unwrap().contains("swap_bytes"));
114    }
115}