Skip to main content

uqa_sql/schema/
retention.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Cancellable admission of immutable catalog column generations and their owned SQL payloads.
8
9use std::sync::Arc;
10use uqa_core::{
11    memory::{
12        Budgeted, BudgetedVec, MemoryBudget, MemoryError, MemoryReservation, Produced,
13        ProductionControl,
14    },
15    CancellationToken, QueryCancelled, Value, ValueRetentionError,
16};
17
18use crate::ast::{ColumnDef, ColumnType, Expr, FunctionBinding};
19
20mod columns;
21mod domains;
22mod expressions;
23mod identities;
24
25#[derive(Debug, thiserror::Error)]
26pub enum CatalogRetentionError {
27    #[error(transparent)]
28    SQL(#[from] crate::SQLError),
29    #[error(transparent)]
30    Memory(#[from] MemoryError),
31    #[error(transparent)]
32    Cancelled(#[from] QueryCancelled),
33    #[error("validated column expression contains a subquery")]
34    UnexpectedSubquery,
35    #[error("malformed {kind} value: {reason}")]
36    Malformed { kind: &'static str, reason: String },
37}
38
39impl From<ValueRetentionError> for CatalogRetentionError {
40    fn from(error: ValueRetentionError) -> Self {
41        match error {
42            ValueRetentionError::Memory(error) => Self::Memory(error),
43            ValueRetentionError::Cancelled(error) => Self::Cancelled(error),
44            ValueRetentionError::Malformed { kind, reason } => Self::Malformed { kind, reason },
45        }
46    }
47}
48
49impl From<CatalogRetentionError> for crate::SQLError {
50    fn from(error: CatalogRetentionError) -> Self {
51        match error {
52            CatalogRetentionError::SQL(error) => error,
53            CatalogRetentionError::Memory(error) => Self::Routine {
54                sqlstate: "53200".into(),
55                message: error.to_string(),
56            },
57            CatalogRetentionError::Cancelled(error) => Self::Cancelled(error),
58            CatalogRetentionError::UnexpectedSubquery => Self::Internal(error.to_string()),
59            CatalogRetentionError::Malformed { .. } => Self::Routine {
60                sqlstate: "XX001".into(),
61                message: error.to_string(),
62            },
63        }
64    }
65}
66
67type Result<T> = std::result::Result<T, CatalogRetentionError>;
68
69/// An admitted immutable column generation. Clones share both the original definitions and one reservation; they do not copy ASTs or reacquire an allowance. Strings, vector capacities, boxed payloads and nested Core values are charged. Allocator/reference-count bookkeeping and Core value map node slack are outside the payload allowance.
70#[derive(Debug, Clone)]
71pub struct RetainedColumns(Arc<Budgeted<Arc<Vec<ColumnDef>>>>);
72
73impl RetainedColumns {
74    /// Admit an existing, SQL-validated generation before acquiring shared ownership. The source remains unchanged on cancellation or quota failure. Subqueries violate the stored column-expression invariant enforced by the default, CHECK and generated-column validators and return a typed error.
75    pub fn capture(
76        columns: &Arc<Vec<ColumnDef>>,
77        budget: &MemoryBudget,
78        cancellation: &CancellationToken,
79    ) -> Result<Self> {
80        let mut walker = Walker::new(budget, cancellation);
81        walker.charge(size_of::<Vec<ColumnDef>>())?;
82        walker.children(columns, Node::Column)?;
83        let memory = walker.finish()?;
84        cancellation.check()?;
85        Ok(Self(
86            Budgeted::new(Arc::clone(columns), memory).into_shared()?,
87        ))
88    }
89
90    pub fn as_slice(&self) -> &[ColumnDef] {
91        &self.0
92    }
93
94    pub fn reserved_bytes(&self) -> usize {
95        self.0.reserved_bytes()
96    }
97}
98
99impl std::ops::Deref for RetainedColumns {
100    type Target = [ColumnDef];
101
102    fn deref(&self) -> &Self::Target {
103        self.as_slice()
104    }
105}
106
107impl ColumnDef {
108    /// Admit owned payloads below this inline column definition without copying them. The returned lease must remain with any retained owner.
109    pub fn reserve_retained_payload(
110        &self,
111        budget: &MemoryBudget,
112        cancellation: &CancellationToken,
113    ) -> Result<MemoryReservation> {
114        Walker::new(budget, cancellation).root(Node::Column(self))
115    }
116}
117
118impl ColumnType {
119    /// Retain a type returned by an external catalog resolver. Its constructor belongs to that resolver; SQL retains the exposed payload before deriving names or traversing the type.
120    pub(crate) fn retain_external_with_control(
121        self,
122        control: &ProductionControl<'_>,
123    ) -> Result<Produced<Self>> {
124        struct Handoff {
125            value: ColumnType,
126            memory: Option<MemoryReservation>,
127        }
128        let mut output = Handoff {
129            value: self,
130            memory: control.empty_reservation(),
131        };
132        control.check()?;
133        if let Some(budget) = control.budget() {
134            let mut walker = Walker::with_control(budget, *control);
135            let result = walker
136                .visit(Node::Type(&output.value))
137                .and_then(|()| walker.drain());
138            let Walker {
139                memory, pending, ..
140            } = walker;
141            drop(pending);
142            output
143                .memory
144                .as_mut()
145                .expect("controlled catalog handoff")
146                .absorb(memory);
147            result?;
148        }
149        Ok(control.finish(output.value, output.memory)?)
150    }
151
152    /// Admit nested type names and boxed base types, excluding this type's inline layout.
153    pub fn reserve_retained_payload(
154        &self,
155        budget: &MemoryBudget,
156        cancellation: &CancellationToken,
157    ) -> Result<MemoryReservation> {
158        Walker::new(budget, cancellation).root(Node::Type(self))
159    }
160}
161
162impl Expr {
163    /// Admit a validated column expression's owned payload, including function bindings and Core values, excluding its inline layout. Traversal is iterative and uses the same allowance. Subqueries violate the stored column-expression invariant and return a typed error.
164    pub fn reserve_column_payload(
165        &self,
166        budget: &MemoryBudget,
167        cancellation: &CancellationToken,
168    ) -> Result<MemoryReservation> {
169        Walker::new(budget, cancellation).root(Node::Expr(self))
170    }
171}
172
173enum Node<'a> {
174    Column(&'a ColumnDef),
175    Domain(&'a crate::catalog::domain::StoredDomain),
176    Type(&'a ColumnType),
177    Expr(&'a Expr),
178    Binding(&'a FunctionBinding),
179}
180
181struct Walker<'a> {
182    memory: MemoryReservation,
183    pending: BudgetedVec<Node<'a>>,
184    control: ProductionControl<'a>,
185}
186
187impl<'a> Walker<'a> {
188    fn new(budget: &'a MemoryBudget, cancellation: &'a CancellationToken) -> Self {
189        Self::with_control(
190            budget,
191            ProductionControl::new(budget, cancellation, cancellation),
192        )
193    }
194
195    fn with_control(budget: &'a MemoryBudget, control: ProductionControl<'a>) -> Self {
196        Self {
197            memory: budget.empty_reservation(),
198            pending: BudgetedVec::new(budget),
199            control,
200        }
201    }
202
203    fn root(mut self, root: Node<'a>) -> Result<MemoryReservation> {
204        self.visit(root)?;
205        self.finish()
206    }
207
208    fn finish(mut self) -> Result<MemoryReservation> {
209        self.drain()?;
210        Ok(self.memory)
211    }
212
213    fn drain(&mut self) -> Result<()> {
214        self.control.check_cancellation()?;
215        while let Some(node) = self.pending.pop() {
216            self.visit(node)?;
217        }
218        Ok(())
219    }
220
221    fn visit(&mut self, node: Node<'a>) -> Result<()> {
222        self.control.check_cancellation()?;
223        match node {
224            Node::Column(column) => self.column(column),
225            Node::Domain(domain) => self.domain(domain),
226            Node::Type(ty) => self.ty(ty),
227            Node::Expr(expr) => self.expr(expr),
228            Node::Binding(binding) => self.binding(binding),
229        }
230    }
231
232    fn node(&mut self, node: Node<'a>) -> Result<()> {
233        self.control.check_cancellation()?;
234        self.pending.push(node)?;
235        Ok(())
236    }
237
238    fn charge(&mut self, bytes: usize) -> Result<()> {
239        self.control.check_cancellation()?;
240        self.memory.grow(bytes)?;
241        Ok(())
242    }
243
244    fn buffer<T>(&mut self, capacity: usize) -> Result<()> {
245        self.charge(
246            capacity
247                .checked_mul(size_of::<T>())
248                .ok_or(MemoryError::SizeOverflow)?,
249        )
250    }
251
252    fn children<T>(&mut self, items: &'a Vec<T>, node: fn(&'a T) -> Node<'a>) -> Result<()> {
253        self.buffer::<T>(items.capacity())?;
254        for item in items {
255            self.node(node(item))?;
256        }
257        Ok(())
258    }
259
260    fn boxed<T>(&mut self, item: &'a T, node: fn(&'a T) -> Node<'a>) -> Result<()> {
261        self.charge(size_of::<T>())?;
262        self.node(node(item))
263    }
264
265    fn text(&mut self, text: &String) -> Result<()> {
266        self.charge(text.capacity())
267    }
268
269    fn optional_text(&mut self, text: Option<&String>) -> Result<()> {
270        if let Some(text) = text {
271            self.text(text)?;
272        }
273        Ok(())
274    }
275
276    fn texts(&mut self, texts: &Vec<String>) -> Result<()> {
277        self.buffer::<String>(texts.capacity())?;
278        for text in texts {
279            self.text(text)?;
280        }
281        Ok(())
282    }
283
284    fn value(&mut self, value: &Value) -> Result<()> {
285        let memory = value.reserve_retained_payload_with_check(self.memory.budget(), || {
286            self.control.check_cancellation()
287        })?;
288        self.memory.absorb(memory);
289        Ok(())
290    }
291
292    fn optional_expr(&mut self, expr: Option<&'a Expr>) -> Result<()> {
293        if let Some(expr) = expr {
294            self.node(Node::Expr(expr))?;
295        }
296        Ok(())
297    }
298
299    fn optional_boxed_expr(&mut self, expr: Option<&'a Expr>) -> Result<()> {
300        if let Some(expr) = expr {
301            self.boxed(expr, Node::Expr)?;
302        }
303        Ok(())
304    }
305}
306
307#[cfg(test)]
308mod tests;