Skip to main content

rustcmdpev_core/
summary.rs

1//! Aggregate metrics computed once over the analyzed plan and consumed by the
2//! renderer's summary block.
3//!
4//! Keeping this in its own module lets rendering pull the data without
5//! re-walking the plan tree, and gives tests a stable surface to assert
6//! against.
7
8use crate::structure::data::buffers::PlanBuffers;
9use crate::structure::data::explain::Explain;
10use crate::structure::data::plan::Plan;
11
12/// Aggregated buffer counters across every node in the plan.
13#[derive(Debug, Clone, Copy, Default)]
14pub struct BufferTotals {
15    pub shared_hit_blocks: u64,
16    pub shared_read_blocks: u64,
17    pub shared_written_blocks: u64,
18    pub shared_dirtied_blocks: u64,
19    pub local_hit_blocks: u64,
20    pub local_read_blocks: u64,
21    pub local_written_blocks: u64,
22    pub local_dirtied_blocks: u64,
23    pub temp_read_blocks: u64,
24    pub temp_written_blocks: u64,
25}
26
27impl BufferTotals {
28    pub fn total(&self) -> u64 {
29        self.shared_hit_blocks
30            + self.shared_read_blocks
31            + self.shared_written_blocks
32            + self.shared_dirtied_blocks
33            + self.local_hit_blocks
34            + self.local_read_blocks
35            + self.local_written_blocks
36            + self.local_dirtied_blocks
37            + self.temp_read_blocks
38            + self.temp_written_blocks
39    }
40
41    pub fn is_empty(&self) -> bool {
42        self.total() == 0
43    }
44
45    fn add(&mut self, b: &PlanBuffers) {
46        self.shared_hit_blocks += b.shared_hit_blocks;
47        self.shared_read_blocks += b.shared_read_blocks;
48        self.shared_written_blocks += b.shared_written_blocks;
49        self.shared_dirtied_blocks += b.shared_dirtied_blocks;
50        self.local_hit_blocks += b.local_hit_blocks;
51        self.local_read_blocks += b.local_read_blocks;
52        self.local_written_blocks += b.local_written_blocks;
53        self.local_dirtied_blocks += b.local_dirtied_blocks;
54        self.temp_read_blocks += b.temp_read_blocks;
55        self.temp_written_blocks += b.temp_written_blocks;
56    }
57}
58
59/// One-shot rollup used to render the header summary block.
60#[derive(Debug, Clone, Copy, Default)]
61pub struct PlanSummary {
62    pub total_cost: f64,
63    pub planning_time: f64,
64    pub execution_time: f64,
65    pub total_loops: u64,
66    pub total_io_read_time: f64,
67    pub total_io_write_time: f64,
68    pub buffers: BufferTotals,
69    pub node_count: u64,
70}
71
72impl PlanSummary {
73    pub fn from_explain(explain: &Explain) -> Self {
74        let mut summary = Self {
75            total_cost: explain.total_cost,
76            planning_time: explain.planning_time,
77            execution_time: explain.execution_time,
78            ..Self::default()
79        };
80        summary.accumulate(&explain.plan);
81        summary
82    }
83
84    fn accumulate(&mut self, plan: &Plan) {
85        self.node_count += 1;
86        self.total_loops = self.total_loops.saturating_add(plan.actuals.actual_loops);
87        self.total_io_read_time += plan.io_timing.io_read_time;
88        self.total_io_write_time += plan.io_timing.io_write_time;
89        self.buffers.add(&plan.buffers);
90        for child in &plan.plans {
91            self.accumulate(child);
92        }
93    }
94}
95
96#[cfg(test)]
97mod tests {
98    use super::*;
99    use crate::structure::data::actuals::PlanActuals;
100
101    fn leaf(loops: u64, hit: u64, read: u64, io_read: f64) -> Plan {
102        let mut plan = Plan::default();
103        plan.identity.node_type = "Seq Scan".into();
104        plan.actuals = PlanActuals {
105            actual_loops: loops,
106            ..PlanActuals::default()
107        };
108        plan.buffers.shared_hit_blocks = hit;
109        plan.buffers.shared_read_blocks = read;
110        plan.io_timing.io_read_time = io_read;
111        plan
112    }
113
114    #[test]
115    fn summary_aggregates_loops_and_buffers_recursively() {
116        let mut root = leaf(3, 5, 0, 0.5);
117        root.identity.node_type = "Hash Join".into();
118        root.plans.push(leaf(2, 7, 1, 0.25));
119        root.plans.push(leaf(4, 0, 2, 0.0));
120        let explain = Explain {
121            total_cost: 12.0,
122            planning_time: 1.5,
123            execution_time: 9.0,
124            plan: root,
125            ..Explain::default()
126        };
127
128        let summary = PlanSummary::from_explain(&explain);
129
130        assert_eq!(summary.node_count, 3);
131        assert_eq!(summary.total_loops, 9);
132        assert_eq!(summary.buffers.shared_hit_blocks, 12);
133        assert_eq!(summary.buffers.shared_read_blocks, 3);
134        assert!((summary.total_io_read_time - 0.75).abs() < 1e-9);
135        assert_eq!(summary.total_cost, 12.0);
136        assert_eq!(summary.planning_time, 1.5);
137        assert_eq!(summary.execution_time, 9.0);
138    }
139
140    #[test]
141    fn summary_buffer_totals_is_empty_when_no_io() {
142        let explain = Explain::default();
143        let summary = PlanSummary::from_explain(&explain);
144        assert!(summary.buffers.is_empty());
145    }
146}