Skip to main content

uqa_execution/query/statement/
retained_owner.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Keep a physical pipeline and its borrowed session inputs in one safe owner, on the caller's thread.
8
9use crate::{Batch, ExecResult, PhysicalOperator, RowSchema};
10use std::num::NonZeroUsize;
11use uqa_core::memory::{MemoryReservation, Produced, ProductionControl, ProductionVec};
12use uqa_sql::SQLError;
13
14/// The host retains the session, statement snapshot, parameters and lexical scope. Execution builds and drives the existing physical pipeline while that owner remains alive.
15pub trait RetainedQueryInput: Send + Sync {
16    fn build(&self) -> Result<Option<Box<dyn PhysicalOperator + '_>>, SQLError>;
17}
18
19type BoundQuery<'a> = Option<Box<dyn PhysicalOperator + 'a>>;
20self_cell::self_cell!(
21    struct QueryCell {
22        owner: Box<dyn RetainedQueryInput>,
23        #[not_covariant]
24        dependent: BoundQuery,
25    }
26);
27
28pub struct RetainedQueryOperator {
29    query: QueryCell,
30    schema: RowSchema,
31    closed: bool,
32    ordering: Produced<Vec<crate::PhysicalOrder>>,
33    memory: Option<MemoryReservation>,
34}
35
36impl RetainedQueryOperator {
37    pub fn try_new(input: Box<dyn RetainedQueryInput>) -> Result<Option<Self>, SQLError> {
38        Self::try_new_with_control(input, &ProductionControl::uncontrolled())
39    }
40
41    pub fn try_new_with_control(
42        input: Box<dyn RetainedQueryInput>,
43        control: &ProductionControl<'_>,
44    ) -> Result<Option<Self>, SQLError> {
45        control.check()?;
46        let query = QueryCell::try_new(input, |input| input.build())?;
47        let Some(schema) =
48            query.with_dependent(|_, input| input.as_ref().map(|input| input.row_schema().clone()))
49        else {
50            return Ok(None);
51        };
52        let mut retained = Self {
53            query,
54            schema,
55            closed: false,
56            ordering: ProductionControl::uncontrolled()
57                .finish(Vec::new(), None)
58                .expect("empty ordering"),
59            memory: None,
60        };
61        let ordering = retained
62            .query
63            .with_dependent(|_, input| -> Result<_, SQLError> {
64                let input = input.as_ref().expect("retained query present");
65                let mut ordering = ProductionVec::new(*control);
66                ordering.reserve(input.output_ordering().len())?;
67                for entry in input.output_ordering() {
68                    ordering.push_produced(
69                        control.finish(entry.clone(), control.empty_reservation())?,
70                    )?;
71                }
72                Ok(ordering.finish()?)
73            });
74        match ordering {
75            Ok(ordering) => {
76                retained.ordering = ordering;
77                Ok(Some(retained))
78            }
79            Err(error) => Err(match retained.close() {
80                Ok(()) => error,
81                Err(cleanup) => error.with_cleanup(
82                    crate::physical::physical_exec_error(cleanup),
83                    "close retained query after ordering construction failure",
84                ),
85            }),
86        }
87    }
88
89    /// Admit the physical wrapper before boxing it; failed admission closes the already owned child pipeline.
90    pub fn into_boxed(mut self, control: &ProductionControl<'_>) -> Result<Box<Self>, SQLError> {
91        match control.reserve(size_of::<Self>()) {
92            Ok(memory) => {
93                self.memory = memory;
94                Ok(Box::new(self))
95            }
96            Err(error) => Err(match self.close() {
97                Ok(()) => SQLError::from(error),
98                Err(cleanup) => SQLError::from(error).with_cleanup(
99                    crate::physical::physical_exec_error(cleanup),
100                    "close retained query after wrapper admission failure",
101                ),
102            }),
103        }
104    }
105}
106
107impl PhysicalOperator for RetainedQueryOperator {
108    fn row_schema(&self) -> &RowSchema {
109        &self.schema
110    }
111    fn estimated_cardinality(&self) -> Option<u64> {
112        self.query.with_dependent(|_, input| {
113            input
114                .as_ref()
115                .and_then(|input| input.estimated_cardinality())
116        })
117    }
118    fn output_ordering(&self) -> &[crate::PhysicalOrder] {
119        &self.ordering
120    }
121    fn backward_scan_support(&self) -> crate::BackwardScanSupport {
122        self.query.with_dependent(|_, input| {
123            input
124                .as_ref()
125                .expect("retained query present")
126                .backward_scan_support()
127        })
128    }
129    fn consume_into_aggregate(
130        &mut self,
131        executor: &mut dyn crate::relational::AggregateExecutor,
132    ) -> ExecResult<bool> {
133        self.query.with_dependent_mut(|_, input| {
134            input
135                .as_mut()
136                .expect("retained query present")
137                .consume_into_aggregate(executor)
138        })
139    }
140    fn next_direction(
141        &mut self,
142        direction: crate::PhysicalScanDirection,
143    ) -> ExecResult<Option<Batch>> {
144        self.query.with_dependent_mut(|_, input| {
145            input
146                .as_mut()
147                .expect("retained query present")
148                .next_direction(direction)
149        })
150    }
151    fn rewind(&mut self) -> ExecResult<()> {
152        self.query
153            .with_dependent_mut(|_, input| input.as_mut().expect("retained query present").rewind())
154    }
155    fn open(&mut self) -> ExecResult<()> {
156        self.closed = false;
157        self.query
158            .with_dependent_mut(|_, input| input.as_mut().expect("retained query present").open())
159    }
160    fn next(&mut self) -> ExecResult<Option<Batch>> {
161        self.query
162            .with_dependent_mut(|_, input| input.as_mut().expect("retained query present").next())
163    }
164    fn next_with_demand(&mut self, rows: NonZeroUsize) -> ExecResult<Option<Batch>> {
165        self.query.with_dependent_mut(|_, input| {
166            input
167                .as_mut()
168                .expect("retained query present")
169                .next_with_demand(rows)
170        })
171    }
172    fn close(&mut self) -> ExecResult<()> {
173        if std::mem::replace(&mut self.closed, true) {
174            return Ok(());
175        }
176        self.query
177            .with_dependent_mut(|_, input| input.as_mut().expect("retained query present").close())
178    }
179}
180impl Drop for RetainedQueryOperator {
181    fn drop(&mut self) {
182        let _ = self.close();
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189    use std::sync::{
190        atomic::{AtomicUsize, Ordering},
191        Arc,
192    };
193
194    struct Input(Arc<AtomicUsize>);
195    struct Source(Arc<AtomicUsize>);
196
197    impl crate::SQLRowSource<crate::PhysicalRow> for Source {
198        fn next_row(&mut self) -> Result<Option<crate::PhysicalRow>, SQLError> {
199            panic!("closing must not fetch a row")
200        }
201        fn close(&mut self) -> Result<(), SQLError> {
202            assert_eq!(self.0.fetch_add(1, Ordering::SeqCst), 0);
203            Err(SQLError::Routine {
204                sqlstate: "58030".into(),
205                message: "retained scan close failed".into(),
206            })
207        }
208    }
209
210    impl RetainedQueryInput for Input {
211        fn build(&self) -> Result<Option<Box<dyn PhysicalOperator + '_>>, SQLError> {
212            Ok(Some(Box::new(crate::PhysicalRowIteratorScan::from_stream(
213                RowSchema::new(vec!["n".into()]),
214                crate::SQLRowStream::from_source(Source(self.0.clone())),
215            ))))
216        }
217    }
218
219    struct OrderedInput {
220        closes: Arc<AtomicUsize>,
221        ordering: Vec<crate::PhysicalOrder>,
222    }
223    struct Ordered<'a> {
224        source: Source,
225        ordering: &'a [crate::PhysicalOrder],
226        schema: RowSchema,
227    }
228    impl PhysicalOperator for Ordered<'_> {
229        fn row_schema(&self) -> &RowSchema {
230            &self.schema
231        }
232        fn output_ordering(&self) -> &[crate::PhysicalOrder] {
233            self.ordering
234        }
235        fn open(&mut self) -> ExecResult<()> {
236            Ok(())
237        }
238        fn next(&mut self) -> ExecResult<Option<Batch>> {
239            panic!("must not fetch")
240        }
241        fn close(&mut self) -> ExecResult<()> {
242            crate::SQLRowSource::close(&mut self.source).map_err(Into::into)
243        }
244    }
245    impl RetainedQueryInput for OrderedInput {
246        fn build(&self) -> Result<Option<Box<dyn PhysicalOperator + '_>>, SQLError> {
247            Ok(Some(Box::new(Ordered {
248                source: Source(self.closes.clone()),
249                ordering: &self.ordering,
250                schema: RowSchema::default(),
251            })))
252        }
253    }
254
255    #[test]
256    fn retained_pipeline_admission_closes_once_and_keeps_cleanup_diagnostics() {
257        use uqa_core::{memory::MemoryBudget, CancellationToken};
258        let budget = MemoryBudget::new(0);
259        let token = CancellationToken::new();
260        let control = ProductionControl::new(&budget, &token, &token);
261        for ordering in [false, true] {
262            let closes = Arc::new(AtomicUsize::new(0));
263            let input = Box::new(OrderedInput {
264                closes: closes.clone(),
265                ordering: if ordering {
266                    vec![
267                        crate::PhysicalOrder {
268                            position: 0,
269                            descending: false,
270                            nulls_first: None,
271                            nullable: false
272                        };
273                        1 << 18
274                    ]
275                } else {
276                    Vec::new()
277                },
278            });
279            let allocation = allocation_counter::measure(|| {
280                let error = if ordering {
281                    RetainedQueryOperator::try_new_with_control(input, &control)
282                        .err()
283                        .unwrap()
284                } else {
285                    RetainedQueryOperator::try_new_with_control(input, &control)
286                        .unwrap()
287                        .unwrap()
288                        .into_boxed(&control)
289                        .err()
290                        .unwrap()
291                };
292                assert_eq!(error.sqlstate(), Some("53200"));
293                assert!(error
294                    .detail()
295                    .unwrap()
296                    .contains("retained scan close failed"));
297            });
298            assert!(allocation.bytes_total < 16 << 10, "{allocation:?}");
299            assert_eq!(closes.load(Ordering::SeqCst), 1);
300            assert_eq!(budget.used(), 0);
301        }
302    }
303
304    #[test]
305    fn retained_pipeline_close_reports_resources_created_before_open() {
306        for open in [false, true] {
307            let closed = Arc::new(AtomicUsize::new(0));
308            let mut pipeline = RetainedQueryOperator::try_new(Box::new(Input(closed.clone())))
309                .unwrap()
310                .unwrap();
311            if open {
312                pipeline.open().unwrap();
313            }
314            let error = crate::physical::physical_exec_error(pipeline.close().unwrap_err());
315            assert_eq!(error.sqlstate(), Some("58030"));
316            pipeline.close().unwrap();
317            drop(pipeline);
318            assert_eq!(closed.load(Ordering::SeqCst), 1);
319        }
320    }
321}