Skip to main content

uqa_execution/query/
measurement.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Measure actual output production without including the receiving sink's work.
8
9use 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/// A relation destination executes EXPLAIN's selected query with its original measurement owner, while retaining its separate declared definition.
35#[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    /// The execution owner starts and finishes one invocation; constructing or describing a destination does not count as execution.
70    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    /// Count rows before handing them to the destination, then exclude only that handoff. Empty batches do not establish startup time.
94    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}