inillucent_sql/bind/scratch.rs
1//! The binder's working vectors: the set it borrows from the connection, and
2//! the subset it saves while a nested block is bound.
3//!
4//! Invariant: **a vector in here is scratch, never part of an answer.** What
5//! [`Binder::bind_statement`] returns owns its own vectors and leaves with
6//! them; everything this module moves about is state the binder keeps while it
7//! works and has no use for afterwards. That is what makes it safe to hand back
8//! to the connection and fill again.
9//!
10//! ## Why this is its own module
11//!
12//! The same reason [`super::cte`] is: `bind.rs` was at the size `policy.rs`
13//! records for it and task-2026 added to it, and that check asks for an
14//! extraction rather than a raised number. The two halves here are one
15//! question - which of the binder's vectors are saved, and who they are given
16//! back to - asked at two scales.
17//!
18//! [`BinderScratch`] is the outer one: the vectors a *connection* keeps
19//! between statements, so a compile pushes into capacity the last compile
20//! took. [`BlockFrame`] is the inner one: the vectors a *query block* borrows
21//! from the block around it, so an aggregate written inside a subquery is
22//! finalised at its own level rather than the enclosing one. Nothing moved
23//! changed in the move.
24
25use super::{
26 Binder, BoundAggregate, BoundExpr, BoundSource, BoundWindow, CteBinding, RecursiveTarget,
27};
28use crate::ast;
29
30/// The vectors a binder works in, kept by the connection rather than made for
31/// every statement.
32///
33/// **The parse arena's counterpart, for the stage after the parse
34/// (task-2026).** `Compiled::scratch_ast` exists because every vector in an
35/// `Ast` is empty at construction and grows on its first push, so a parse that
36/// is thrown away a microsecond later pays the allocator for capacity it
37/// already had last time. The binder has exactly that shape and was not getting
38/// that treatment: binding `SELECT 1` took the scope stack's buffer and the
39/// result-alias buffer - 96 and 320 bytes - out of the allocator on every
40/// compile, and `prepare.trivial` is a workload the gate compiles on every
41/// iteration.
42///
43/// What is here is the binder's own working state. What the binder *returns* is
44/// not: a `BoundStatement`'s vectors leave with it and belong to whoever asked
45/// for the bind, so recycling them would mean handing back memory something
46/// else is still reading.
47///
48/// Like the arena, it is cleared on the way in rather than on the way out, and
49/// it keeps whatever capacity the largest statement so far needed - a
50/// connection that once bound a statement with ten thousand FROM terms holds
51/// that much `sources` until it closes. That is the trade [`crate::ast::Ast`]
52/// already makes, made once more here rather than differently.
53#[derive(Default)]
54pub struct BinderScratch {
55 sources: Vec<BoundSource>,
56 scopes: Vec<Vec<usize>>,
57 aggregates: Vec<BoundAggregate>,
58 result_aliases: Vec<(Vec<u8>, BoundExpr)>,
59 schemas: Vec<(usize, u32)>,
60 ctes: Vec<Vec<CteBinding>>,
61 recursing: Vec<RecursiveTarget>,
62 binding_ctes: Vec<ast::SelectId>,
63 correlations: Vec<usize>,
64 windows: Vec<BoundWindow>,
65 named_windows: Vec<(Vec<u8>, ast::WindowId)>,
66 firing: Vec<Vec<u8>>,
67 firing_foreign_keys: Vec<Vec<u8>>,
68 pending_constraints: Vec<BoundExpr>,
69}
70
71impl BinderScratch {
72 /// Returns a scratch with nothing in it and nothing allocated.
73 pub fn new() -> BinderScratch {
74 BinderScratch::default()
75 }
76
77 /// Empties every vector, keeping the memory each has already taken.
78 ///
79 /// A `clear` rather than a `new` for the reason [`crate::ast::Ast::clear`]
80 /// gives: the capacity is the point, and dropping it would leave a scratch
81 /// that costs an allocation to refill.
82 fn clear(&mut self) {
83 self.sources.clear();
84 self.scopes.clear();
85 self.aggregates.clear();
86 self.result_aliases.clear();
87 self.schemas.clear();
88 self.ctes.clear();
89 self.recursing.clear();
90 self.binding_ctes.clear();
91 self.correlations.clear();
92 self.windows.clear();
93 self.named_windows.clear();
94 self.firing.clear();
95 self.firing_foreign_keys.clear();
96 self.pending_constraints.clear();
97 }
98}
99
100/// The per-block binder state saved while a nested block is bound.
101///
102/// Aggregates, result aliases and the correlation list all belong to one query
103/// block. Without a frame, an aggregate written inside a subquery would be
104/// added to the enclosing block's accumulator list and finalised at the wrong
105/// level - which is a wrong answer rather than an error.
106pub(super) struct BlockFrame {
107 windows: Vec<BoundWindow>,
108 named_windows: Vec<(Vec<u8>, ast::WindowId)>,
109 aggregates: Vec<BoundAggregate>,
110 result_aliases: Vec<(Vec<u8>, BoundExpr)>,
111 allow_aggregates: bool,
112 inside_aggregate: bool,
113 correlations: Vec<usize>,
114 tail_may_name_an_alias: bool,
115}
116
117impl<'a> Binder<'a> {
118 /// Binds into vectors the caller keeps, rather than into fresh ones.
119 ///
120 /// **For a caller that binds one statement after another**, which is every
121 /// connection: the scratch is cleared on the way in, so the second bind
122 /// pushes into capacity the first one took. See [`BinderScratch`] for what
123 /// is in it and what is deliberately not.
124 ///
125 /// @param scratch - the vectors to fill, cleared first
126 pub fn with_scratch(mut self, mut scratch: BinderScratch) -> Binder<'a> {
127 scratch.clear();
128 self.sources = scratch.sources;
129 self.scopes = scratch.scopes;
130 self.aggregates = scratch.aggregates;
131 self.result_aliases = scratch.result_aliases;
132 self.dependencies.schemas = scratch.schemas;
133 self.ctes = scratch.ctes;
134 self.recursing = scratch.recursing;
135 self.binding_ctes = scratch.binding_ctes;
136 self.correlations = scratch.correlations;
137 self.windows = scratch.windows;
138 self.named_windows = scratch.named_windows;
139 self.firing = scratch.firing;
140 self.firing_foreign_keys = scratch.firing_foreign_keys;
141 self.pending_constraints = scratch.pending_constraints;
142 self
143 }
144
145 /// Returns the vectors this bind filled, for the next bind to reuse.
146 ///
147 /// The binder is consumed, so nothing can still be reading what is handed
148 /// back. The bound statement is not in here - it was returned by
149 /// [`Binder::bind_statement`] and owns its own vectors.
150 pub fn into_scratch(self) -> BinderScratch {
151 BinderScratch {
152 sources: self.sources,
153 scopes: self.scopes,
154 aggregates: self.aggregates,
155 result_aliases: self.result_aliases,
156 schemas: self.dependencies.schemas,
157 ctes: self.ctes,
158 recursing: self.recursing,
159 binding_ctes: self.binding_ctes,
160 correlations: self.correlations,
161 windows: self.windows,
162 named_windows: self.named_windows,
163 firing: self.firing,
164 firing_foreign_keys: self.firing_foreign_keys,
165 pending_constraints: self.pending_constraints,
166 }
167 }
168
169 /// Opens a query block: a fresh scope, and fresh per-block state.
170 pub(super) fn enter_block(&mut self) -> BlockFrame {
171 self.scopes.push(Vec::new());
172 BlockFrame {
173 windows: core::mem::take(&mut self.windows),
174 named_windows: core::mem::take(&mut self.named_windows),
175 aggregates: core::mem::take(&mut self.aggregates),
176 result_aliases: core::mem::take(&mut self.result_aliases),
177 allow_aggregates: core::mem::replace(&mut self.allow_aggregates, false),
178 inside_aggregate: core::mem::replace(&mut self.inside_aggregate, false),
179 correlations: core::mem::take(&mut self.correlations),
180 tail_may_name_an_alias: self.tail_may_name_an_alias,
181 }
182 }
183
184 /// Closes a query block, returning the FROM terms it owned.
185 ///
186 /// A correlation the closing block recorded is passed outward when the
187 /// block that is now innermost does not own the term either, which is what
188 /// makes correlation transitive through two levels of nesting.
189 pub(super) fn leave_block(&mut self, frame: BlockFrame) -> Vec<usize> {
190 let ids = self.scopes.pop().unwrap_or_default();
191 let inner = core::mem::replace(&mut self.correlations, frame.correlations);
192 for id in inner {
193 if ids.contains(&id) {
194 continue;
195 }
196 let owned = self.scopes.last().is_some_and(|scope| scope.contains(&id));
197 if !owned && !self.correlations.contains(&id) {
198 self.correlations.push(id);
199 }
200 }
201 self.windows = frame.windows;
202 self.named_windows = frame.named_windows;
203 self.aggregates = frame.aggregates;
204 self.result_aliases = frame.result_aliases;
205 self.allow_aggregates = frame.allow_aggregates;
206 self.inside_aggregate = frame.inside_aggregate;
207 self.tail_may_name_an_alias = frame.tail_may_name_an_alias;
208 ids
209 }
210}