uqa_execution/query/
measurement.rs1use super::diagnostics::io::Operation;
10use std::{
11 cell::Cell,
12 time::{Duration, Instant},
13};
14use uqa_core::{
15 io_usage::{IOContext, IOUsage},
16 memory::MemoryBudget,
17};
18use uqa_sql::{result::explain::ExplainNodeMetrics, SQLError};
19
20#[cfg(test)]
21mod io_tests;
22#[cfg(test)]
23mod tests;
24
25pub struct QueryMeasurement {
26 clock: Option<fn() -> Instant>,
27 running: Cell<Option<Running>>,
28 completed: Cell<ExplainNodeMetrics>,
29 io: Cell<IOUsage>,
30 parent: IOContext,
31 memory: MemoryBudget,
32}
33
34#[derive(Clone, Copy)]
36pub struct ExplainedQuery<'a> {
37 pub plan: &'a uqa_sql::plan::QueryPlan,
38 pub measurement: &'a QueryMeasurement,
39}
40
41#[derive(Clone, Copy)]
42struct Running {
43 started: Option<Instant>,
44 downstream: Duration,
45 first_output: Option<Duration>,
46 rows: u64,
47}
48
49impl QueryMeasurement {
50 pub(crate) fn new(timing: bool, memory: &MemoryBudget) -> Self {
51 Self {
52 clock: timing.then_some(Instant::now),
53 running: Cell::new(None),
54 completed: Cell::new(ExplainNodeMetrics::default()),
55 io: Cell::new(IOUsage::default()),
56 parent: IOContext::current(),
57 memory: memory.clone(),
58 }
59 }
60
61 pub(crate) fn metrics(&self) -> ExplainNodeMetrics {
62 self.completed.get()
63 }
64
65 pub(crate) fn io(&self) -> IOUsage {
66 self.io.get()
67 }
68
69 pub(crate) fn run<T>(
71 &self,
72 execute: impl FnOnce() -> Result<T, SQLError>,
73 ) -> Result<T, SQLError> {
74 if self.running.get().is_some() {
75 return Err(SQLError::Internal(
76 "query measurement already executing".into(),
77 ));
78 }
79 let io = Operation::enter(&self.parent, &self.memory)?;
80 self.running.set(Some(Running {
81 started: self.now(),
82 downstream: Duration::ZERO,
83 first_output: None,
84 rows: 0,
85 }));
86 let guard = Invocation(self);
87 let result = execute();
88 let completed = self.finish(io.as_ref());
89 drop(guard);
90 combine(result, completed)
91 }
92
93 pub(crate) fn output<T>(
95 &self,
96 rows: usize,
97 consume: impl FnOnce() -> Result<T, SQLError>,
98 ) -> Result<T, SQLError> {
99 let mut running = self.running.get().ok_or_else(inactive)?;
100 running.rows = running
101 .rows
102 .checked_add(u64::try_from(rows).map_err(|_| overflow())?)
103 .ok_or_else(overflow)?;
104 if rows != 0 && running.first_output.is_none() {
105 running.first_output = Some(self.elapsed(running)?);
106 }
107 self.running.set(Some(running));
108 let started = self.now();
109 let _parent = self.parent.enter();
110 let result = consume();
111 let paused = self.pause(started);
112 combine(result, paused)
113 }
114
115 fn now(&self) -> Option<Instant> {
116 self.clock.map(|now| now())
117 }
118
119 fn elapsed(&self, running: Running) -> Result<Duration, SQLError> {
120 match running.started {
121 Some(started) => self
122 .now()
123 .expect("timed invocation")
124 .checked_duration_since(started)
125 .and_then(|elapsed| elapsed.checked_sub(running.downstream))
126 .ok_or_else(overflow),
127 None => Ok(Duration::ZERO),
128 }
129 }
130
131 fn pause(&self, started: Option<Instant>) -> Result<(), SQLError> {
132 if let Some(started) = started {
133 let mut running = self.running.get().ok_or_else(inactive)?;
134 running.downstream = running
135 .downstream
136 .checked_add(
137 self.now()
138 .expect("timed destination")
139 .checked_duration_since(started)
140 .ok_or_else(overflow)?,
141 )
142 .ok_or_else(overflow)?;
143 self.running.set(Some(running));
144 }
145 Ok(())
146 }
147
148 fn finish(&self, operation: Option<&Operation>) -> Result<(), SQLError> {
149 let running = self.running.get().ok_or_else(inactive)?;
150 let elapsed = self.elapsed(running)?;
151 let completed = self.completed.get();
152 let io = self
153 .io
154 .get()
155 .checked_add(operation.map_or(Ok(IOUsage::default()), Operation::finish)?)
156 .ok_or_else(overflow)?;
157 let completed = ExplainNodeMetrics {
158 rows: completed
159 .rows
160 .checked_add(running.rows)
161 .ok_or_else(overflow)?,
162 loops: completed.loops.checked_add(1).ok_or_else(overflow)?,
163 startup: completed
164 .startup
165 .checked_add(running.first_output.unwrap_or(elapsed))
166 .ok_or_else(overflow)?,
167 total: completed.total.checked_add(elapsed).ok_or_else(overflow)?,
168 };
169 self.completed.set(completed);
170 self.io.set(io);
171 Ok(())
172 }
173}
174
175struct Invocation<'a>(&'a QueryMeasurement);
176
177impl Drop for Invocation<'_> {
178 fn drop(&mut self) {
179 self.0.running.set(None);
180 }
181}
182
183fn inactive() -> SQLError {
184 SQLError::Internal("query output measurement has no executing invocation".into())
185}
186
187fn overflow() -> SQLError {
188 SQLError::Internal("EXPLAIN execution measurements overflowed".into())
189}
190
191fn combine<T>(
192 result: Result<T, SQLError>,
193 accounting: Result<(), SQLError>,
194) -> Result<T, SQLError> {
195 match (result, accounting) {
196 (Ok(value), Ok(())) => Ok(value),
197 (Err(error), Ok(())) | (Ok(_), Err(error)) => Err(error),
198 (Err(error), Err(accounting)) => {
199 Err(error.with_cleanup(accounting, "record EXPLAIN execution measurements"))
200 }
201 }
202}