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 rows;
11pub(crate) use rows::RowConstructorState;
12use uqa_sql::expr::composites::constructor::CompositeConstructorState;
13
14use crate::RowSchema;
15
16use uqa_core::{memory::Produced, Value};
17use uqa_sql::{
18    ast::{BinaryOp, FunctionBinding, FunctionDispatch},
19    expr::enums::EnumComparisonState,
20    routines::invocation::descriptions::RoutineCallDescriptions,
21    ScalarExpr,
22};
23
24#[cfg(test)]
25thread_local! {
26    static COMPARISON_LOOKUPS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
27    pub(super) static CAST_TYPE_RESOLUTIONS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
28    pub(super) static COLUMN_NAME_LOOKUPS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
29}
30
31/// The first conversion of a cast whose operand is a literal.
32#[derive(Debug)]
33pub(crate) enum ConstantCast {
34    /// An immutable conversion, which every later evaluation copies.
35    Retained(Value),
36    /// The conversion reads a catalog descriptor, a session setting or a type outside the builtin scalars, so every evaluation converts again.
37    PerEvaluation,
38}
39
40/// 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.
41#[derive(Debug)]
42pub(crate) enum RowCast {
43    Catalog {
44        conversion: Box<uqa_sql::expr::RetainedCatalogCast>,
45        source: Option<Produced<String>>,
46        schema: Option<RowSchema>,
47    },
48    Resolved {
49        conversion: uqa_sql::expr::ResolvedCast,
50        source: Produced<String>,
51        schema: Option<RowSchema>,
52    },
53    Source {
54        source: Option<Produced<String>>,
55        schema: Option<RowSchema>,
56    },
57}
58
59/// A fixed numeric overload tied to the immutable schema that selected it.
60#[derive(Debug)]
61pub(crate) enum NumericCall {
62    Resolved {
63        operation: uqa_sql::expr::ResolvedNumericOperator,
64        schema: Option<RowSchema>,
65    },
66    PerEvaluation,
67}
68
69/// The context schema the resolution of a column reference depended on.
70#[derive(Debug)]
71pub(crate) enum ContextSchema {
72    /// A qualified reference never consults the context schema.
73    Unused,
74    /// The context carried no schema.
75    Absent,
76    /// The context carried this schema, which decided between a column and a whole-row reference.
77    Shared(RowSchema),
78}
79
80/// The key a column reference reads once the schema of its rows is known.
81#[derive(Debug)]
82pub(crate) struct ColumnSlot {
83    pub(crate) context_schema: ContextSchema,
84    /// The schema the rows resolved the reference through. Retaining it keeps the index alive, so a later schema can never reuse its address.
85    pub(crate) row_schema: RowSchema,
86    /// The space of `key`: rows of the same schema read through a lookup of another space resolve the name again.
87    pub(crate) key_space: uqa_sql::expr::RowKeySpace,
88    /// The row lookup's key for the reference, or `None` for a name the rows do not carry.
89    pub(crate) key: Option<usize>,
90}
91
92/// Read-only lookup into the function state owned by a prepared expression set.
93/// 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.
94#[derive(Debug, Default)]
95pub struct FunctionCallStates {
96    routines: Vec<(usize, RoutineCallDescriptions)>,
97    enums: Vec<((usize, u8), EnumComparisonState)>,
98    constant_casts: Vec<(usize, OnceLock<ConstantCast>)>,
99    columns: Vec<(usize, OnceLock<ColumnSlot>)>,
100    row_casts: Vec<(usize, OnceLock<RowCast>)>,
101    numeric_operators: Vec<(usize, OnceLock<NumericCall>)>,
102    row_constructors: Vec<(usize, RowConstructorState)>,
103    composite_constructors: Vec<(usize, CompositeConstructorState)>,
104}
105
106impl FunctionCallStates {
107    fn register(&mut self, expression: &ScalarExpr) {
108        let first_row_cast = self.row_casts.len();
109        let first_numeric = self.numeric_operators.len();
110        let mut parameter_dependent = false;
111        expression.visit(&mut |expression| match expression {
112            ScalarExpr::Func { name, binding, args, .. } => {
113                self.add(args.as_ptr() as usize, function_slots(name, binding.as_ref(), args));
114                if let Some(invocation) = binding.as_ref().filter(|binding| !binding.builtin).and_then(|binding| binding.invocation.as_deref()) {
115                    self.routines.push((std::ptr::from_ref(invocation) as usize, RoutineCallDescriptions::default()));
116                }
117                if binding.as_ref().is_some_and(|binding| binding.builtin
118                    && matches!(binding.dispatch, Some(FunctionDispatch::NumericOperator(operator)) if args.len() == operator.arity())) {
119                    self.numeric_operators.push((args.as_ptr() as usize, OnceLock::new()));
120                }
121            }
122            ScalarExpr::Binary {
123                op: BinaryOp::Less | BinaryOp::LessEqual | BinaryOp::Greater | BinaryOp::GreaterEqual,
124                lhs, ..
125            } => self.add(std::ptr::from_ref(lhs.as_ref()) as usize, 1),
126            ScalarExpr::Between { low, high, .. } => {
127                self.add(std::ptr::from_ref(low.as_ref()) as usize, 1);
128                self.add(std::ptr::from_ref(high.as_ref()) as usize, 1);
129            }
130            ScalarExpr::Cast { expr, .. }
131                if matches!(expr.as_ref(), ScalarExpr::Literal(_) | ScalarExpr::TypedLiteral { .. }) =>
132            {
133                self.constant_casts
134                    .push((std::ptr::from_ref(expr.as_ref()) as usize, OnceLock::new()));
135            }
136            ScalarExpr::Cast { expr, .. } => {
137                self.row_casts.push((std::ptr::from_ref(expr.as_ref()) as usize, OnceLock::new()));
138            }
139            ScalarExpr::Row(items) => self.row_constructors.push((items.as_ptr() as usize, RowConstructorState::default())),
140            ScalarExpr::CompositeRow { items, .. } => self.composite_constructors.push((items.as_ptr() as usize, CompositeConstructorState::default())),
141            ScalarExpr::Param(_) => parameter_dependent = true,
142            ScalarExpr::Column(_) | ScalarExpr::QualifiedColumn { .. } => {
143                self.columns
144                    .push((std::ptr::from_ref(expression) as usize, OnceLock::new()));
145            }
146            _ => {},
147        });
148        // One traversal per root avoids rescanning every nested cast's subtree. Parameter-dependent roots keep live inference without disabling independent roots.
149        if parameter_dependent {
150            self.row_casts.truncate(first_row_cast);
151            self.numeric_operators.truncate(first_numeric);
152        }
153    }
154
155    fn is_empty(&self) -> bool {
156        self.routines.is_empty()
157            && self.enums.is_empty()
158            && self.constant_casts.is_empty()
159            && self.columns.is_empty()
160            && self.row_casts.is_empty()
161            && self.numeric_operators.is_empty()
162            && self.row_constructors.is_empty()
163            && self.composite_constructors.is_empty()
164    }
165
166    pub(crate) fn routine(&self, binding: &FunctionBinding) -> Option<&RoutineCallDescriptions> {
167        let address = std::ptr::from_ref(binding.invocation.as_deref()?) as usize;
168        self.routines
169            .binary_search_by_key(&address, |(key, _)| *key)
170            .ok()
171            .map(|index| &self.routines[index].1)
172    }
173
174    /// The retained key of the column reference `expression`.
175    pub(crate) fn column_slot(&self, expression: &ScalarExpr) -> Option<&OnceLock<ColumnSlot>> {
176        let address = std::ptr::from_ref(expression) as usize;
177        self.columns
178            .binary_search_by_key(&address, |(key, _)| *key)
179            .ok()
180            .map(|index| &self.columns[index].1)
181    }
182
183    /// The retained first conversion of the cast whose literal operand is `operand`.
184    pub(crate) fn constant_cast(&self, operand: &ScalarExpr) -> Option<&OnceLock<ConstantCast>> {
185        let address = std::ptr::from_ref(operand) as usize;
186        self.constant_casts
187            .binary_search_by_key(&address, |(key, _)| *key)
188            .ok()
189            .map(|index| &self.constant_casts[index].1)
190    }
191
192    pub(crate) fn row_cast(&self, operand: &ScalarExpr) -> Option<&OnceLock<RowCast>> {
193        let address = std::ptr::from_ref(operand) as usize;
194        self.row_casts
195            .binary_search_by_key(&address, |(key, _)| *key)
196            .ok()
197            .map(|index| &self.row_casts[index].1)
198    }
199
200    pub(crate) fn numeric_operator(
201        &self,
202        arguments: &[ScalarExpr],
203    ) -> Option<&OnceLock<NumericCall>> {
204        let address = arguments.as_ptr() as usize;
205        self.numeric_operators
206            .binary_search_by_key(&address, |(key, _)| *key)
207            .ok()
208            .map(|index| &self.numeric_operators[index].1)
209    }
210
211    pub(crate) fn row_constructor(&self, items: &[ScalarExpr]) -> Option<&RowConstructorState> {
212        self.row_constructors
213            .binary_search_by_key(&(items.as_ptr() as usize), |(key, _)| *key)
214            .ok()
215            .map(|index| &self.row_constructors[index].1)
216    }
217    pub(crate) fn composite_constructor(
218        &self,
219        items: &[ScalarExpr],
220    ) -> Option<&CompositeConstructorState> {
221        self.composite_constructors
222            .binary_search_by_key(&(items.as_ptr() as usize), |(key, _)| *key)
223            .ok()
224            .map(|index| &self.composite_constructors[index].1)
225    }
226
227    fn add(&mut self, address: usize, slots: u8) {
228        for slot in 0..slots {
229            self.enums
230                .push(((address, slot), EnumComparisonState::default()));
231        }
232    }
233
234    pub(crate) fn enum_comparisons(
235        &self,
236        arguments: &[ScalarExpr],
237    ) -> [Option<&EnumComparisonState>; 4] {
238        let address = arguments.as_ptr() as usize;
239        let Ok(first) = self
240            .enums
241            .binary_search_by_key(&(address, 0), |(key, _)| *key)
242        else {
243            return [None; 4];
244        };
245        std::array::from_fn(|slot| {
246            self.enums
247                .get(first + slot)
248                .filter(|(key, _)| *key == (address, slot as u8))
249                .map(|(_, state)| state)
250        })
251    }
252
253    pub(crate) fn enum_binary_comparison(&self, left: &ScalarExpr) -> Option<&EnumComparisonState> {
254        #[cfg(test)]
255        COMPARISON_LOOKUPS.with(|count| count.set(count.get() + 1));
256        self.enums
257            .binary_search_by_key(&(std::ptr::from_ref(left) as usize, 0), |(key, _)| *key)
258            .ok()
259            .map(|index| &self.enums[index].1)
260    }
261}
262
263fn function_slots(name: &str, binding: Option<&FunctionBinding>, args: &[ScalarExpr]) -> u8 {
264    if binding.is_some_and(|binding| !binding.builtin) {
265        return 0;
266    }
267    match binding.and_then(|binding| binding.dispatch) {
268        Some(FunctionDispatch::Enum { operation, .. }) => {
269            u8::from(args.len() == 2 && operation.uses_comparison_state())
270        }
271        Some(FunctionDispatch::AnyOperator | FunctionDispatch::AllOperator) => u8::from(
272            args.len() == 3
273                && matches!(args.last(),
274                Some(ScalarExpr::Literal(uqa_core::Value::Str(op)))
275                    if matches!(op.as_str(), "<" | "<=" | ">" | ">=")),
276        ),
277        Some(FunctionDispatch::BetweenSymmetric) if args.len() == 3 => 4,
278        None => u8::from(
279            args.len() >= 2
280                && (name.eq_ignore_ascii_case("greatest") || name.eq_ignore_ascii_case("least")),
281        ),
282        _ => 0,
283    }
284}
285
286type VisitRoots<T> = fn(&T, &mut dyn FnMut(&ScalarExpr));
287
288/// Retains both the immutable source and its call state. Argument vectors and
289/// comparison operands are heap allocations, so their identity survives moves. They cannot
290/// be changed or freed while the state is usable; addresses are only lookup keys
291/// and are never dereferenced. Cloning prepares independent, initially empty state.
292pub(crate) struct PreparedExpressions<T> {
293    expressions: T,
294    calls: Option<Box<PreparedCallStates<T>>>,
295}
296
297struct PreparedCallStates<T> {
298    calls: FunctionCallStates,
299    visit_roots: VisitRoots<T>,
300}
301
302static EMPTY_CALL_STATES: FunctionCallStates = FunctionCallStates {
303    routines: Vec::new(),
304    enums: Vec::new(),
305    constant_casts: Vec::new(),
306    columns: Vec::new(),
307    row_casts: Vec::new(),
308    numeric_operators: Vec::new(),
309    row_constructors: Vec::new(),
310    composite_constructors: Vec::new(),
311};
312
313impl<T> PreparedExpressions<T> {
314    pub(crate) fn new(expressions: T, visit_roots: VisitRoots<T>) -> Self {
315        let mut calls = FunctionCallStates::default();
316        visit_roots(&expressions, &mut |expression| calls.register(expression));
317        calls.routines.sort_unstable_by_key(|(address, _)| *address);
318        calls.routines.dedup_by_key(|(address, _)| *address);
319        calls.enums.sort_unstable_by_key(|(address, _)| *address);
320        calls.enums.dedup_by_key(|(address, _)| *address);
321        calls
322            .constant_casts
323            .sort_unstable_by_key(|(address, _)| *address);
324        calls.constant_casts.dedup_by_key(|(address, _)| *address);
325        calls.columns.sort_unstable_by_key(|(address, _)| *address);
326        calls.columns.dedup_by_key(|(address, _)| *address);
327        calls
328            .row_casts
329            .sort_unstable_by_key(|(address, _)| *address);
330        calls.row_casts.dedup_by_key(|(address, _)| *address);
331        calls
332            .numeric_operators
333            .sort_unstable_by_key(|(address, _)| *address);
334        calls
335            .numeric_operators
336            .dedup_by_key(|(address, _)| *address);
337        calls
338            .row_constructors
339            .sort_unstable_by_key(|(address, _)| *address);
340        calls.row_constructors.dedup_by_key(|(address, _)| *address);
341        calls
342            .composite_constructors
343            .sort_unstable_by_key(|(address, _)| *address);
344        calls
345            .composite_constructors
346            .dedup_by_key(|(address, _)| *address);
347        Self {
348            expressions,
349            calls: (!calls.is_empty()).then(|| Box::new(PreparedCallStates { calls, visit_roots })),
350        }
351    }
352
353    pub(crate) fn calls(&self) -> &FunctionCallStates {
354        self.calls
355            .as_ref()
356            .map_or(&EMPTY_CALL_STATES, |calls| &calls.calls)
357    }
358}
359
360impl PreparedExpressions<ScalarExpr> {
361    pub(crate) fn scalar(expression: ScalarExpr) -> Self {
362        Self::new(expression, |expression, visit| visit(expression))
363    }
364}
365
366impl PreparedExpressions<Vec<ScalarExpr>> {
367    pub(crate) fn scalars(expressions: Vec<ScalarExpr>) -> Self {
368        Self::new(expressions, |expressions, visit| {
369            expressions.iter().for_each(visit);
370        })
371    }
372}
373
374impl PreparedExpressions<Vec<crate::SortKey>> {
375    pub(crate) fn sort_keys(keys: Vec<crate::SortKey>) -> Self {
376        Self::new(keys, |keys, visit| {
377            for key in keys {
378                visit(&key.expr);
379            }
380        })
381    }
382}
383
384impl<T> std::ops::Deref for PreparedExpressions<T> {
385    type Target = T;
386
387    fn deref(&self) -> &T {
388        &self.expressions
389    }
390}
391
392impl<T: Clone> Clone for PreparedExpressions<T> {
393    fn clone(&self) -> Self {
394        match self.calls.as_ref() {
395            Some(calls) => Self::new(self.expressions.clone(), calls.visit_roots),
396            None => Self {
397                expressions: self.expressions.clone(),
398                calls: None,
399            },
400        }
401    }
402}
403
404#[cfg(test)]
405mod tests;