Skip to main content

uqa_execution/query/sources/
retained_source.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Execution ownership of SQL-invisible, repeatable row sources.
8
9use std::cell::RefCell;
10use std::collections::btree_map::Entry;
11use std::collections::BTreeMap;
12use std::marker::PhantomData;
13use std::rc::Rc;
14use std::sync::Arc;
15
16use uqa_sql::ast::{InternalRelationId, RetainedRowSource};
17use uqa_sql::SQLError;
18
19use crate::{SharedSpill, SharedSpillScan};
20
21#[derive(Clone)]
22struct RetainedRows {
23    rows: SharedSpill,
24    admitted_types: Option<Arc<[Option<String>]>>,
25}
26
27#[cfg(test)]
28mod tests;
29
30thread_local! {
31    static ACTIVE_ROWS: RefCell<Arc<BTreeMap<InternalRelationId, RetainedRows>>> = RefCell::default();
32}
33
34/// Immutable owners captured for a statement's workers. Capturing and entering a context share the spill owners without copying rows or their metadata maps.
35#[derive(Clone, Default)]
36pub struct RetainedRowContext(Arc<BTreeMap<InternalRelationId, RetainedRows>>);
37
38impl RetainedRowContext {
39    #[must_use]
40    pub fn current() -> Self {
41        ACTIVE_ROWS.with(|active| Self(active.borrow().clone()))
42    }
43
44    pub(crate) fn enter(&self) -> RetainedRowThreadScope {
45        RetainedRowThreadScope {
46            previous: ACTIVE_ROWS.with(|active| active.replace(self.0.clone())),
47            _thread: PhantomData,
48        }
49    }
50}
51
52pub(crate) struct RetainedRowThreadScope {
53    previous: Arc<BTreeMap<InternalRelationId, RetainedRows>>,
54    _thread: PhantomData<Rc<()>>,
55}
56
57impl Drop for RetainedRowThreadScope {
58    fn drop(&mut self) {
59        ACTIVE_ROWS.with(|active| {
60            std::mem::swap(&mut *active.borrow_mut(), &mut self.previous);
61        });
62    }
63}
64
65/// Own one source until its synchronous action finishes. Nested actions have independent opaque identities; an error or unwind removes exactly this source. The guard cannot move to another thread, while an opened scan owns its independent spill reader.
66pub struct RetainedRowScope {
67    descriptor: RetainedRowSource,
68    _thread: PhantomData<Rc<()>>,
69}
70
71impl RetainedRowScope {
72    pub fn enter(relation: InternalRelationId, rows: SharedSpill) -> Result<Self, SQLError> {
73        Self::register(relation, rows, None)
74    }
75
76    /// Preserve the read-time semantics of typed constants without evaluating them before statement analysis. Whole-row values with no declared type stay unchanged.
77    pub(crate) fn enter_admitted(
78        relation: InternalRelationId,
79        rows: SharedSpill,
80        types: Arc<[Option<String>]>,
81    ) -> Result<Self, SQLError> {
82        if types.len() != rows.row_schema().physical_width() {
83            return Err(SQLError::Internal(
84                "retained constant types do not match their row width".into(),
85            ));
86        }
87        Self::register(relation, rows, Some(types))
88    }
89
90    fn register(
91        relation: InternalRelationId,
92        rows: SharedSpill,
93        admitted_types: Option<Arc<[Option<String>]>>,
94    ) -> Result<Self, SQLError> {
95        let descriptor = RetainedRowSource::new(relation, rows.row_schema().clone(), rows.rows())?;
96        ACTIVE_ROWS.with(|active| {
97            match Arc::make_mut(&mut active.borrow_mut()).entry(relation) {
98                Entry::Occupied(_) => Err(SQLError::Internal(
99                    "retained row source is already active".into(),
100                )),
101                Entry::Vacant(entry) => {
102                    entry.insert(RetainedRows {
103                        rows,
104                        admitted_types,
105                    });
106                    Ok(())
107                }
108            }
109        })?;
110        Ok(Self {
111            descriptor,
112            _thread: PhantomData,
113        })
114    }
115
116    pub fn descriptor(&self) -> &RetainedRowSource {
117        &self.descriptor
118    }
119}
120
121impl Drop for RetainedRowScope {
122    fn drop(&mut self) {
123        ACTIVE_ROWS.with(|active| {
124            let removed =
125                Arc::make_mut(&mut active.borrow_mut()).remove(&self.descriptor.relation());
126            debug_assert!(removed.is_some(), "retained row source ownership was lost");
127        });
128    }
129}
130
131fn retained_rows(source: &RetainedRowSource) -> Result<RetainedRows, SQLError> {
132    ACTIVE_ROWS.with(|active| {
133        let active = active.borrow();
134        let rows = active.get(&source.relation()).ok_or_else(|| {
135            SQLError::Internal("retained row source is outside its execution scope".into())
136        })?;
137        if rows.rows.rows() != source.rows() || rows.rows.row_schema() != source.schema() {
138            return Err(SQLError::Internal(
139                "retained row source does not match its declared rows and schema".into(),
140            ));
141        }
142        Ok(rows.clone())
143    })
144}
145
146#[cfg(test)]
147pub(crate) fn build_retained_source(
148    source: &RetainedRowSource,
149) -> Result<SharedSpillScan, SQLError> {
150    Ok(SharedSpillScan::new(retained_rows(source)?.rows))
151}
152
153pub(super) fn build_retained_source_operator<S: Clone + Send + Sync + 'static>(
154    context: &super::SourceContext<'_, S>,
155    source: &RetainedRowSource,
156    ctes: &super::CteScope<S>,
157) -> Result<SharedSpillScan, SQLError> {
158    let retained = retained_rows(source)?;
159    let rows = if let Some(types) = retained.admitted_types {
160        let hook = context.relational.expression_scope(ctes.clone());
161        read_admitted_rows(
162            retained.rows,
163            &types,
164            hook.as_ref(),
165            context.relational.runtime.work_mem_bytes()?,
166            context.relational.runtime.cancellation,
167        )?
168    } else {
169        retained.rows
170    };
171    Ok(SharedSpillScan::new(rows))
172}
173
174fn read_admitted_rows(
175    rows: SharedSpill,
176    types: &[Option<String>],
177    hook: &dyn uqa_sql::expr::EngineHook,
178    work_mem: usize,
179    cancellation: &uqa_core::CancellationToken,
180) -> Result<SharedSpill, SQLError> {
181    use crate::physical::physical_exec_error;
182    use crate::{PhysicalOperator, PhysicalRow, SpillBuffer};
183    use uqa_core::memory::ProductionControl;
184    use uqa_sql::expr::composites::literal::{contains_records, evaluate_with_control};
185
186    cancellation.check()?;
187    let schema = rows.row_schema().clone();
188    let mut input = SharedSpillScan::new(rows);
189    let mut output = SpillBuffer::new(work_mem / 2);
190    let mut writer =
191        crate::spill::SpillBatchWriter::new(schema.clone()).map_err(physical_exec_error)?;
192    input.open().map_err(physical_exec_error)?;
193    while let Some(batch) = input.next().map_err(physical_exec_error)? {
194        for row in batch.rows {
195            cancellation.check()?;
196            let mut values = row.into_physical_values();
197            for (value, ty) in values.iter_mut().zip(types) {
198                let Some(ty) = ty.as_deref().filter(|_| contains_records(value)) else {
199                    continue;
200                };
201                *value = evaluate_with_control(
202                    value,
203                    ty,
204                    Some(hook),
205                    &ProductionControl::uncontrolled(),
206                )?
207                .into_uncontrolled()
208                .expect("ordinary admitted rule input");
209            }
210            writer
211                .push(&mut output, PhysicalRow::from_values(values))
212                .map_err(physical_exec_error)?;
213        }
214    }
215    input.close().map_err(physical_exec_error)?;
216    cancellation.check()?;
217    writer.finish(&mut output).map_err(physical_exec_error)?;
218    output.into_shared(schema).map_err(physical_exec_error)
219}