Skip to main content

uqa_execution/scalar/
state.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Function state belongs to immutable expressions prepared for one execution.
8
9use std::sync::OnceLock;
10mod entries;
11mod rows;
12use entries::StateEntries;
13pub(crate) use rows::RowConstructorState;
14use uqa_sql::expr::composites::constructor::CompositeConstructorState;
15
16use crate::RowSchema;
17
18use uqa_core::{
19    memory::{Produced, ProductionControl},
20    Value,
21};
22use uqa_sql::SQLError;
23use uqa_sql::{
24    ast::{BinaryOp, FunctionBinding, FunctionDispatch},
25    expr::enums::EnumComparisonState,
26    routines::invocation::descriptions::RoutineCallDescriptions,
27    ScalarExpr,
28};
29
30#[cfg(test)]
31thread_local! {
32    static COMPARISON_LOOKUPS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
33    pub(super) static CAST_TYPE_RESOLUTIONS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
34    pub(super) static COLUMN_NAME_LOOKUPS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
35}
36
37/// The first conversion of a cast whose operand is a literal.
38#[derive(Debug)]
39pub(crate) enum ConstantCast {
40    /// An immutable conversion, which every later evaluation copies.
41    Retained(Value),
42    /// The conversion reads a catalog descriptor, a session setting or a type outside the builtin scalars, so every evaluation converts again.
43    PerEvaluation,
44}
45
46/// Catalog-free source inference is retained for the same immutable execution schema. Explicit builtin conversions retain their descriptor. Bound catalog casts may retain type descriptions under an opt-in immutable catalog identity; unqualified names and live custom catalogs keep per-evaluation resolution.
47#[derive(Debug)]
48pub(crate) enum RowCast {
49    Catalog {
50        conversion: Box<uqa_sql::expr::RetainedCatalogCast>,
51        source: Option<Produced<String>>,
52        schema: Option<RowSchema>,
53    },
54    Resolved {
55        conversion: uqa_sql::expr::ResolvedCast,
56        source: Produced<String>,
57        schema: Option<RowSchema>,
58    },
59    Source {
60        source: Option<Produced<String>>,
61        schema: Option<RowSchema>,
62    },
63}
64
65/// A fixed numeric overload tied to the immutable schema that selected it.
66#[derive(Debug)]
67pub(crate) enum NumericCall {
68    Resolved {
69        operation: uqa_sql::expr::ResolvedNumericOperator,
70        schema: Option<RowSchema>,
71    },
72    PerEvaluation,
73}
74
75/// The context schema the resolution of a column reference depended on.
76#[derive(Debug)]
77pub(crate) enum ContextSchema {
78    /// A qualified reference never consults the context schema.
79    Unused,
80    /// The context carried no schema.
81    Absent,
82    /// The context carried this schema, which decided between a column and a whole-row reference.
83    Shared(RowSchema),
84}
85
86/// The key a column reference reads once the schema of its rows is known.
87#[derive(Debug)]
88pub(crate) struct ColumnSlot {
89    pub(crate) context_schema: ContextSchema,
90    /// The schema the rows resolved the reference through. Retaining it keeps the index alive, so a later schema can never reuse its address.
91    pub(crate) row_schema: RowSchema,
92    /// The space of `key`: rows of the same schema read through a lookup of another space resolve the name again.
93    pub(crate) key_space: uqa_sql::expr::RowKeySpace,
94    /// The row lookup's key for the reference, or `None` for a name the rows do not carry.
95    pub(crate) key: Option<usize>,
96}
97
98/// Read-only lookup into the function state owned by a prepared expression set.
99/// The state has one fixed-size entry per logical routine call, ordering comparison, numeric operator, literal/row cast, column reference or composite constructor, never per input row.
100#[derive(Debug, Default)]
101pub struct FunctionCallStates {
102    routines: Vec<(usize, RoutineCallDescriptions)>,
103    enums: Vec<((usize, u8), EnumComparisonState)>,
104    constant_casts: Vec<(usize, OnceLock<ConstantCast>)>,
105    columns: Vec<(usize, OnceLock<ColumnSlot>)>,
106    row_casts: Vec<(usize, OnceLock<RowCast>)>,
107    numeric_operators: Vec<(usize, OnceLock<NumericCall>)>,
108    row_constructors: Vec<(usize, RowConstructorState)>,
109    composite_constructors: Vec<(usize, CompositeConstructorState)>,
110}
111
112struct CallStateBuilder {
113    routines: StateEntries<(usize, RoutineCallDescriptions)>,
114    enums: StateEntries<((usize, u8), EnumComparisonState)>,
115    constant_casts: StateEntries<(usize, OnceLock<ConstantCast>)>,
116    columns: StateEntries<(usize, OnceLock<ColumnSlot>)>,
117    row_casts: StateEntries<(usize, OnceLock<RowCast>)>,
118    numeric_operators: StateEntries<(usize, OnceLock<NumericCall>)>,
119    row_constructors: StateEntries<(usize, RowConstructorState)>,
120    composite_constructors: StateEntries<(usize, CompositeConstructorState)>,
121}
122
123impl CallStateBuilder {
124    fn with_control(control: &ProductionControl<'_>) -> Self {
125        Self {
126            routines: StateEntries::new(control),
127            enums: StateEntries::new(control),
128            constant_casts: StateEntries::new(control),
129            columns: StateEntries::new(control),
130            row_casts: StateEntries::new(control),
131            numeric_operators: StateEntries::new(control),
132            row_constructors: StateEntries::new(control),
133            composite_constructors: StateEntries::new(control),
134        }
135    }
136
137    fn register(
138        &mut self,
139        expression: &ScalarExpr,
140        control: &ProductionControl<'_>,
141    ) -> Result<(), SQLError> {
142        let first_row_cast = self.row_casts.len();
143        let first_numeric = self.numeric_operators.len();
144        let mut parameter_dependent = false;
145        expression.try_visit(&mut |expression| {
146            control.check()?;
147            match expression {
148            ScalarExpr::Func { name, binding, args, .. } => {
149                self.add(args.as_ptr() as usize, function_slots(name, binding.as_ref(), args))?;
150                if let Some(invocation) = binding.as_ref().filter(|binding| !binding.builtin).and_then(|binding| binding.invocation.as_deref()) {
151                    self.routines.push((std::ptr::from_ref(invocation) as usize, RoutineCallDescriptions::default()))?;
152                }
153                if binding.as_ref().is_some_and(|binding| binding.builtin
154                    && matches!(binding.dispatch, Some(FunctionDispatch::NumericOperator(operator)) if args.len() == operator.arity())) {
155                    self.numeric_operators.push((args.as_ptr() as usize, OnceLock::new()))?;
156                }
157            }
158            ScalarExpr::Binary {
159                op: BinaryOp::Less | BinaryOp::LessEqual | BinaryOp::Greater | BinaryOp::GreaterEqual,
160                lhs, ..
161            } => self.add(std::ptr::from_ref(lhs.as_ref()) as usize, 1)?,
162            ScalarExpr::Between { low, high, .. } => {
163                self.add(std::ptr::from_ref(low.as_ref()) as usize, 1)?;
164                self.add(std::ptr::from_ref(high.as_ref()) as usize, 1)?;
165            }
166            ScalarExpr::Cast { expr, .. }
167                if matches!(expr.as_ref(), ScalarExpr::Literal(_) | ScalarExpr::TypedLiteral { .. }) =>
168            {
169                self.constant_casts
170                    .push((std::ptr::from_ref(expr.as_ref()) as usize, OnceLock::new()))?;
171            }
172            ScalarExpr::Cast { expr, .. } => {
173                self.row_casts.push((std::ptr::from_ref(expr.as_ref()) as usize, OnceLock::new()))?;
174            }
175            ScalarExpr::Row(items) => self.row_constructors.push((items.as_ptr() as usize, RowConstructorState::default()))?,
176            ScalarExpr::CompositeRow { items, .. } => self.composite_constructors.push((items.as_ptr() as usize, CompositeConstructorState::default()))?,
177            ScalarExpr::Param(_) => parameter_dependent = true,
178            ScalarExpr::Column(_) | ScalarExpr::QualifiedColumn { .. } => {
179                self.columns
180                    .push((std::ptr::from_ref(expression) as usize, OnceLock::new()))?;
181            }
182            _ => {},
183            }
184            Ok::<_, SQLError>(true)
185        })?;
186        // One traversal per root avoids rescanning every nested cast's subtree. Parameter-dependent roots keep live inference without disabling independent roots.
187        if parameter_dependent {
188            self.row_casts.truncate(first_row_cast);
189            self.numeric_operators.truncate(first_numeric);
190        }
191        Ok(())
192    }
193
194    fn add(&mut self, address: usize, slots: u8) -> Result<(), SQLError> {
195        for slot in 0..slots {
196            self.enums
197                .push(((address, slot), EnumComparisonState::default()))?;
198        }
199        Ok(())
200    }
201
202    fn finish(
203        self,
204        control: &ProductionControl<'_>,
205    ) -> Result<Produced<FunctionCallStates>, SQLError> {
206        let mut memory = control.empty_reservation();
207        let (routines, lease) = self.routines.into_parts();
208        memory = control.combine(memory, lease);
209        let (enums, lease) = self.enums.into_parts();
210        memory = control.combine(memory, lease);
211        let (constant_casts, lease) = self.constant_casts.into_parts();
212        memory = control.combine(memory, lease);
213        let (columns, lease) = self.columns.into_parts();
214        memory = control.combine(memory, lease);
215        let (row_casts, lease) = self.row_casts.into_parts();
216        memory = control.combine(memory, lease);
217        let (numeric_operators, lease) = self.numeric_operators.into_parts();
218        memory = control.combine(memory, lease);
219        let (row_constructors, lease) = self.row_constructors.into_parts();
220        memory = control.combine(memory, lease);
221        let (composite_constructors, lease) = self.composite_constructors.into_parts();
222        memory = control.combine(memory, lease);
223        Ok(control.finish(
224            FunctionCallStates {
225                routines,
226                enums,
227                constant_casts,
228                columns,
229                row_casts,
230                numeric_operators,
231                row_constructors,
232                composite_constructors,
233            },
234            memory,
235        )?)
236    }
237}
238
239impl FunctionCallStates {
240    fn is_empty(&self) -> bool {
241        self.routines.is_empty()
242            && self.enums.is_empty()
243            && self.constant_casts.is_empty()
244            && self.columns.is_empty()
245            && self.row_casts.is_empty()
246            && self.numeric_operators.is_empty()
247            && self.row_constructors.is_empty()
248            && self.composite_constructors.is_empty()
249    }
250
251    pub(crate) fn routine(&self, binding: &FunctionBinding) -> Option<&RoutineCallDescriptions> {
252        let address = std::ptr::from_ref(binding.invocation.as_deref()?) as usize;
253        self.routines
254            .binary_search_by_key(&address, |(key, _)| *key)
255            .ok()
256            .map(|index| &self.routines[index].1)
257    }
258
259    /// The retained key of the column reference `expression`.
260    pub(crate) fn column_slot(&self, expression: &ScalarExpr) -> Option<&OnceLock<ColumnSlot>> {
261        let address = std::ptr::from_ref(expression) as usize;
262        self.columns
263            .binary_search_by_key(&address, |(key, _)| *key)
264            .ok()
265            .map(|index| &self.columns[index].1)
266    }
267
268    /// The retained first conversion of the cast whose literal operand is `operand`.
269    pub(crate) fn constant_cast(&self, operand: &ScalarExpr) -> Option<&OnceLock<ConstantCast>> {
270        let address = std::ptr::from_ref(operand) as usize;
271        self.constant_casts
272            .binary_search_by_key(&address, |(key, _)| *key)
273            .ok()
274            .map(|index| &self.constant_casts[index].1)
275    }
276
277    pub(crate) fn row_cast(&self, operand: &ScalarExpr) -> Option<&OnceLock<RowCast>> {
278        let address = std::ptr::from_ref(operand) as usize;
279        self.row_casts
280            .binary_search_by_key(&address, |(key, _)| *key)
281            .ok()
282            .map(|index| &self.row_casts[index].1)
283    }
284
285    pub(crate) fn numeric_operator(
286        &self,
287        arguments: &[ScalarExpr],
288    ) -> Option<&OnceLock<NumericCall>> {
289        let address = arguments.as_ptr() as usize;
290        self.numeric_operators
291            .binary_search_by_key(&address, |(key, _)| *key)
292            .ok()
293            .map(|index| &self.numeric_operators[index].1)
294    }
295
296    pub(crate) fn row_constructor(&self, items: &[ScalarExpr]) -> Option<&RowConstructorState> {
297        self.row_constructors
298            .binary_search_by_key(&(items.as_ptr() as usize), |(key, _)| *key)
299            .ok()
300            .map(|index| &self.row_constructors[index].1)
301    }
302    pub(crate) fn composite_constructor(
303        &self,
304        items: &[ScalarExpr],
305    ) -> Option<&CompositeConstructorState> {
306        self.composite_constructors
307            .binary_search_by_key(&(items.as_ptr() as usize), |(key, _)| *key)
308            .ok()
309            .map(|index| &self.composite_constructors[index].1)
310    }
311
312    pub(crate) fn enum_comparisons(
313        &self,
314        arguments: &[ScalarExpr],
315    ) -> [Option<&EnumComparisonState>; 4] {
316        let address = arguments.as_ptr() as usize;
317        let Ok(first) = self
318            .enums
319            .binary_search_by_key(&(address, 0), |(key, _)| *key)
320        else {
321            return [None; 4];
322        };
323        std::array::from_fn(|slot| {
324            self.enums
325                .get(first + slot)
326                .filter(|(key, _)| *key == (address, slot as u8))
327                .map(|(_, state)| state)
328        })
329    }
330
331    pub(crate) fn enum_binary_comparison(&self, left: &ScalarExpr) -> Option<&EnumComparisonState> {
332        #[cfg(test)]
333        COMPARISON_LOOKUPS.with(|count| count.set(count.get() + 1));
334        self.enums
335            .binary_search_by_key(&(std::ptr::from_ref(left) as usize, 0), |(key, _)| *key)
336            .ok()
337            .map(|index| &self.enums[index].1)
338    }
339}
340
341fn function_slots(name: &str, binding: Option<&FunctionBinding>, args: &[ScalarExpr]) -> u8 {
342    if binding.is_some_and(|binding| !binding.builtin) {
343        return 0;
344    }
345    match binding.and_then(|binding| binding.dispatch) {
346        Some(FunctionDispatch::Enum { operation, .. }) => {
347            u8::from(args.len() == 2 && operation.uses_comparison_state())
348        }
349        Some(FunctionDispatch::AnyOperator | FunctionDispatch::AllOperator) => u8::from(
350            args.len() == 3
351                && matches!(args.last(),
352                Some(ScalarExpr::Literal(uqa_core::Value::Str(op)))
353                    if matches!(op.as_str(), "<" | "<=" | ">" | ">=")),
354        ),
355        Some(FunctionDispatch::BetweenSymmetric) if args.len() == 3 => 4,
356        None => u8::from(
357            args.len() >= 2
358                && (name.eq_ignore_ascii_case("greatest") || name.eq_ignore_ascii_case("least")),
359        ),
360        _ => 0,
361    }
362}
363
364type VisitRoots<T> =
365    fn(&T, &mut dyn FnMut(&ScalarExpr) -> Result<(), SQLError>) -> Result<(), SQLError>;
366
367/// Retains both the immutable source and its call state. Argument vectors and
368/// comparison operands are heap allocations, so their identity survives moves. They cannot
369/// be changed or freed while the state is usable; addresses are only lookup keys
370/// and are never dereferenced. Cloning prepares independent, initially empty state.
371pub(crate) struct PreparedExpressions<T> {
372    expressions: T,
373    calls: Option<Box<Produced<PreparedCallStates<T>>>>,
374}
375
376struct PreparedCallStates<T> {
377    calls: FunctionCallStates,
378    visit_roots: VisitRoots<T>,
379}
380
381static EMPTY_CALL_STATES: FunctionCallStates = FunctionCallStates {
382    routines: Vec::new(),
383    enums: Vec::new(),
384    constant_casts: Vec::new(),
385    columns: Vec::new(),
386    row_casts: Vec::new(),
387    numeric_operators: Vec::new(),
388    row_constructors: Vec::new(),
389    composite_constructors: Vec::new(),
390};
391
392impl<T> PreparedExpressions<T> {
393    pub(crate) fn new(expressions: T, visit_roots: VisitRoots<T>) -> Self {
394        Self::new_with_control(expressions, visit_roots, &ProductionControl::uncontrolled())
395            .expect("ordinary immutable expression preparation")
396    }
397
398    pub(crate) fn new_with_control(
399        expressions: T,
400        visit_roots: VisitRoots<T>,
401        control: &ProductionControl<'_>,
402    ) -> Result<Self, SQLError> {
403        control.check()?;
404        let mut calls = CallStateBuilder::with_control(control);
405        visit_roots(&expressions, &mut |expression| {
406            calls.register(expression, control)
407        })?;
408        calls.routines.sort_unstable_by_key(|(address, _)| *address);
409        calls.routines.dedup_by_key(|(address, _)| *address);
410        calls.enums.sort_unstable_by_key(|(address, _)| *address);
411        calls.enums.dedup_by_key(|(address, _)| *address);
412        calls
413            .constant_casts
414            .sort_unstable_by_key(|(address, _)| *address);
415        calls.constant_casts.dedup_by_key(|(address, _)| *address);
416        calls.columns.sort_unstable_by_key(|(address, _)| *address);
417        calls.columns.dedup_by_key(|(address, _)| *address);
418        calls
419            .row_casts
420            .sort_unstable_by_key(|(address, _)| *address);
421        calls.row_casts.dedup_by_key(|(address, _)| *address);
422        calls
423            .numeric_operators
424            .sort_unstable_by_key(|(address, _)| *address);
425        calls
426            .numeric_operators
427            .dedup_by_key(|(address, _)| *address);
428        calls
429            .row_constructors
430            .sort_unstable_by_key(|(address, _)| *address);
431        calls.row_constructors.dedup_by_key(|(address, _)| *address);
432        calls
433            .composite_constructors
434            .sort_unstable_by_key(|(address, _)| *address);
435        calls
436            .composite_constructors
437            .dedup_by_key(|(address, _)| *address);
438        let calls = calls.finish(control)?;
439        let calls = if calls.is_empty() {
440            None
441        } else {
442            let header = control.reserve(size_of::<Produced<PreparedCallStates<T>>>())?;
443            let (calls, memory) = calls.into_parts();
444            Some(Box::new(control.finish(
445                PreparedCallStates { calls, visit_roots },
446                control.combine(memory, header),
447            )?))
448        };
449        control.check()?;
450        Ok(Self { expressions, calls })
451    }
452
453    pub(crate) fn calls(&self) -> &FunctionCallStates {
454        self.calls
455            .as_ref()
456            .map_or(&EMPTY_CALL_STATES, |calls| &calls.calls)
457    }
458}
459
460impl PreparedExpressions<ScalarExpr> {
461    pub(crate) fn scalar(expression: ScalarExpr) -> Self {
462        Self::new(expression, |expression, visit| visit(expression))
463    }
464}
465
466impl PreparedExpressions<Produced<ScalarExpr>> {
467    pub(crate) fn produced_scalar(
468        expression: Produced<ScalarExpr>,
469        control: &ProductionControl<'_>,
470    ) -> Result<Self, SQLError> {
471        Self::new_with_control(expression, |expression, visit| visit(expression), control)
472    }
473}
474
475impl PreparedExpressions<Vec<ScalarExpr>> {
476    pub(crate) fn scalars(expressions: Vec<ScalarExpr>) -> Self {
477        Self::new(expressions, |expressions, visit| {
478            expressions.iter().try_for_each(visit)
479        })
480    }
481}
482
483impl PreparedExpressions<Produced<Vec<ScalarExpr>>> {
484    pub(crate) fn produced_scalars(
485        expressions: Produced<Vec<ScalarExpr>>,
486        control: &ProductionControl<'_>,
487    ) -> Result<Self, SQLError> {
488        Self::new_with_control(
489            expressions,
490            |expressions, visit| expressions.iter().try_for_each(visit),
491            control,
492        )
493    }
494}
495
496impl PreparedExpressions<Vec<crate::SortKey>> {
497    pub(crate) fn sort_keys(keys: Vec<crate::SortKey>) -> Self {
498        Self::new(keys, |keys, visit| {
499            for key in keys {
500                visit(&key.expr)?;
501            }
502            Ok(())
503        })
504    }
505}
506
507impl<T> std::ops::Deref for PreparedExpressions<T> {
508    type Target = T;
509
510    fn deref(&self) -> &T {
511        &self.expressions
512    }
513}
514
515impl<T: Clone> Clone for PreparedExpressions<T> {
516    fn clone(&self) -> Self {
517        match self.calls.as_ref() {
518            Some(calls) => Self::new(self.expressions.clone(), calls.visit_roots),
519            None => Self {
520                expressions: self.expressions.clone(),
521                calls: None,
522            },
523        }
524    }
525}
526
527#[cfg(test)]
528mod tests;
529
530#[cfg(test)]
531mod production_tests;