ingraph_codegen/aggregate/emit.rs
1//! The AGGREGATE's emission: the record it mounts, and the fold that fills it.
2//!
3//! # It emits a RECORD, and that is most of the design
4//!
5//! [`Mounted`] holds the two halves the front end built: the `(group…, measure…)` row parsed by the
6//! ORDINARY record pass, and the declaration that says how the row is filled. So a mounted
7//! aggregate has the `*Key` type, the per-database rows, the `find_<db>` / `upsert_<db>` doors, the
8//! order-by vocabulary, the cursor, the `<Node>Due` clock vocabulary and the polling apparatus that
9//! every declared record has — because it IS one — and this file adds exactly the one thing a
10//! record cannot say: what a group's rows fold into.
11//!
12//! That is `#[ingraph::journal]`'s shape verbatim, one kind over. The two differ in what they mint:
13//! a journal mints the WHOLE row and refuses an author who wrote a field, and an aggregate mints
14//! none of it — the author declared every column — and mints the KEY instead, which is the one
15//! thing about the shape their two role words decide rather than write.
16//!
17//! # The RECOMPUTE is a fold and TWO REACHES, not three emissions
18//!
19//! The closed design's trigger reads the upstream's rows, groups them, folds each group and upserts
20//! one row per group. Two of those four steps are the record machinery's own and arrive with the
21//! mount above — `Upstream::find_<db>(…).fetch()` is the read and `Self::upsert_<db>(…)` is the
22//! keyed replace, both emitted by the record pass for both nodes — so what is written HERE is the
23//! middle: [`AggregateModel::fold`], every row in, one row per group out.
24//!
25//! **The keyed replace is why duplicates cannot accumulate, and the immunity is structural rather
26//! than checked.** A recompute consumes a TABLE: running it twice over one table state writes the
27//! same rows to the same addresses, and a row the upstream no longer holds simply stops being
28//! counted. Nothing dedups, nothing retracts, and there is no tombstone contract — see the kind's
29//! own note in [`super`].
30//!
31//! # WHY THE PARTITION IS A LINEAR PROBE OVER [`PartialEq`]
32//!
33//! A group key is a tuple of the declaration's own group columns, whose types are the AUTHOR's.
34//! Hashing would demand `Hash + Eq` of every one of them and sorting would demand `Ord`, and both
35//! are a bound this fold does not need: the answer is the same either way, and the cost is a walk
36//! over the groups a table HAS rather than over its rows. A codec census has a dozen groups and a
37//! per-language duration has a hundred, so the quadratic term is over the small number — and what
38//! it buys is that a column keyed by a type with an equality and no ordering is declarable at all.
39//!
40//! # THE MEASURE CALLS ARE STATIC, and the item type is written rather than inferred
41//!
42//! A declaration names its measure at compile time, so every fold is a monomorphized call on a
43//! concrete citizen: no wire enum, no visitor, no dynamic dispatch. Each is spelled
44//! `<F as Measure<T>>::fold(…)` in fully qualified form with `T` written out, because [`Counting`]
45//! implements the trait at EVERY item type there is — an inferred call over it is `E0282`, which is
46//! the measurement its own `NAME` const records one crate over.
47//!
48//! [`Counting`]: ../../../ingraph/measure/struct.Counting.html
49//! [`Measure`]: ../../../ingraph/measure/trait.Measure.html
50
51use proc_macro2::TokenStream;
52use quote::{format_ident, quote, quote_spanned};
53use syn::spanned::Spanned as _;
54
55use super::{AggregateModel, Measure, Measured, Owed};
56use crate::{
57 emit::{framework, leading},
58 model::RecordModel,
59};
60
61#[cfg(test)]
62mod tests;
63
64/// A MOUNTED aggregate: the record it IS, and the declaration that folds into it.
65///
66/// PLAIN, for the reason every model in this crate has plain fields: the derive today and a
67/// manifest front end later reach the same emitter.
68///
69/// Two models rather than one flattened, which is `JournalModel`'s own shape: the record half is
70/// the record pass's output and is not this grammar's to edit, and the aggregate half is every word
71/// the record grammar has no seat for. A reader of either knows which authority wrote it.
72#[derive(Debug, Clone)]
73pub struct Mounted {
74 /// The record this aggregate IS — the author's columns, keyed by the group projection, parsed by
75 /// the ordinary record pass under [`NodeKind::Aggregate`](crate::model::NodeKind::Aggregate).
76 pub record: RecordModel,
77 /// The declaration that fills it: the upstream, the group projection and the measures.
78 pub aggregate: AggregateModel,
79}
80
81impl Mounted {
82 /// The record's own expansion, and the fold over it.
83 #[must_use]
84 pub fn emit(&self) -> TokenStream {
85 let record = self.record.emit();
86 let fold = self.aggregate.fold();
87 quote! {
88 #record
89 #fold
90 }
91 }
92}
93
94impl AggregateModel {
95 /// `fn fold(rows: &[Upstream]) -> Vec<Self>` — the recompute's whole arithmetic.
96 ///
97 /// An INHERENT method inside the anonymous const, which is where every inherent item this crate
98 /// emits lands: it binds no framework trait, it is reached as `<Aggregate>::fold`, and a name that
99 /// leaked into the declarer's scope would be a second thing the declaration brought into being
100 /// without saying so.
101 ///
102 /// # The signature is the declaration's two ends and nothing between them
103 ///
104 /// `&[Upstream]` in, because the read is the record machinery's — an aggregate's upstream is a
105 /// record, so `Upstream::find_<db>(pool).fetch()` is already emitted at ITS declaration and this
106 /// one would be a second door onto one lane. `Vec<Self>` out, because the write is too: each row
107 /// goes to `Self::upsert_<db>`, whose keyed replace is what makes a whole recompute safe to run
108 /// on every tick.
109 ///
110 /// Nothing here is `async` and nothing here fails. A fold over values in memory has no await to
111 /// spend and no refusal to make — the two ends that can are the two the record pass owns — so the
112 /// answer is a `Vec` rather than a `Result` a caller would `?` over unconditionally.
113 pub(crate) fn fold(&self) -> TokenStream {
114 let (aggregate, vis) = (&self.aggregate, &self.vis);
115 let upstream = &self.upstream;
116 let measure = framework(&self.krate, &["measure"], "Measure");
117
118 let held = quote!(::std::vec::Vec<&#upstream>);
119 let key_types = self.groups.iter().map(|grouped| &grouped.ty);
120 let key_reads = self
121 .groups
122 .iter()
123 .map(|grouped| read(upstream, &grouped.from));
124 let key_binds: Vec<&syn::Ident> = self.groups.iter().map(|grouped| &grouped.field).collect();
125 let filled = self
126 .measures
127 .iter()
128 .map(|measured| self.measured(measured, &measure));
129
130 let doc = leading(&format!(
131 "Fold every row `{upstream}` holds into one [`{aggregate}`] per group.",
132 upstream = path_text(upstream),
133 ));
134 let whole = leading(
135 "The recompute's ARITHMETIC, and the recompute is WHOLE: it consumes the upstream's rows as a \
136 TABLE rather than as messages, so running it twice over one table state writes the same rows \
137 to the same addresses, and a row the upstream no longer holds simply stops being counted. \
138 Duplicate delivery cannot reach it and deletion needs no retraction — both fall out of the \
139 shape rather than being checked.",
140 );
141 let ends = leading(&format!(
142 "The two ENDS are the record machinery's, reached rather than restated: read the upstream's \
143 table with its own `find_<db>(…).fetch()`, hand the rows here, and write each answer back \
144 through [`{aggregate}`]'s `upsert_<db>`, whose KEYED REPLACE is what makes running this on \
145 every tick safe."
146 ));
147 let ordering = leading(
148 "The rows come back in FIRST-SEEN group order — the order the upstream's rows presented the \
149 groups in — which is not a sort and is not promised to be one: a caller that wants an order \
150 reads the table back through the query lane, where an order is written.",
151 );
152
153 quote! {
154 impl #aggregate {
155 #[doc = #doc]
156 #[doc = ""]
157 #[doc = #whole]
158 #[doc = ""]
159 #[doc = #ends]
160 #[doc = ""]
161 #[doc = #ordering]
162 #[must_use]
163 // EVERY COLUMN READ IS A CLONE, and a macro cannot know which of them is a `Copy`. The
164 // borrowing accessor is the one every column has, so the read is `Clone::clone` over its
165 // answer — and over a `Copy` column that is `clone_on_copy`, a default-on lint, reported
166 // inside an expansion its author cannot edit and fatal to any consumer building under
167 // `-D warnings`. The record's own conversions dodge it by call FORM, taking a reference to
168 // a PLACE; there is no place here, the value arriving from a call, so the lint is answered
169 // where it fires. `allow` and not `expect` for `wide_signature`'s reason: an unfulfilled
170 // `expect` is itself a warning, so a declaration whose every column is non-`Copy` would
171 // fail on the silencer.
172 #[allow(clippy::clone_on_copy)]
173 #vis fn fold(__ig_rows: &[#upstream]) -> ::std::vec::Vec<Self> {
174 let mut __ig_groups: ::std::vec::Vec<((#(#key_types,)*), #held)> =
175 ::std::vec::Vec::new();
176 for __ig_row in __ig_rows {
177 let __ig_key = (#(#key_reads,)*);
178 match __ig_groups
179 .iter_mut()
180 .find(|(__ig_seen, _)| *__ig_seen == __ig_key)
181 {
182 ::core::option::Option::Some((_, __ig_held)) => __ig_held.push(__ig_row),
183 ::core::option::Option::None => {
184 let mut __ig_first: #held = ::std::vec::Vec::new();
185 __ig_first.push(__ig_row);
186 __ig_groups.push((__ig_key, __ig_first));
187 }
188 }
189 }
190 __ig_groups
191 .into_iter()
192 .map(|((#(#key_binds,)*), __ig_held)| Self {
193 #(#key_binds,)*
194 #(#filled)*
195 })
196 .collect()
197 }
198 }
199 }
200 }
201
202 /// ONE measure column, as the field it fills and the static call that fills it.
203 ///
204 /// # `Owed` decides WHAT THE SLICE IS, which is the whole of what this position asks it
205 ///
206 /// The axis the grammar checked the `from` seat against answers the emission's own question one
207 /// step later. A fold that owes its entry a COLUMN is handed that column's values, cloned out of
208 /// each row of the group; a fold that owes NOTHING is handed the group's ROWS, which is what
209 /// `counting` wants — it answers how many there are about items of every type there is. A fold the
210 /// declaring crate wrote takes whichever its entry named, because what it reads is its author's
211 /// knowledge and the grammar refused neither spelling.
212 ///
213 /// # The CITIZEN is `Default`-constructed, and a shipped word and a quoted path meet there
214 ///
215 /// The elected-fold seat one kind over resolves its shorthand into a path and constructs both the
216 /// same way, and this is that law read at the second position that has it: a bare word names a
217 /// framework citizen, a quoted path names the declaring crate's own type, and neither is
218 /// privileged at the construction. A fold with no [`Default`] is `E0277` at the entry that named
219 /// it, which is where its author can act on it.
220 fn measured(&self, measured: &Measured, measure: &TokenStream) -> TokenStream {
221 let field = &measured.field;
222 let at = field.span();
223 let fold = self.citizen(&measured.by);
224 let built = quote_spanned!(at=> <#fold as ::core::default::Default>::default());
225 let upstream = &self.upstream;
226
227 let value = match (measured.by.owed(), measured.from.as_ref()) {
228 // THE COLUMN: the fold reads one, so the slice is that column's values. Cloned rather than
229 // borrowed because a fold takes `&[T]` over items and the values live one field inside rows
230 // this walk does not own.
231 (Owed::Column | Owed::Theirs, Some(from)) => {
232 let read = read(upstream, from);
233 quote_spanned! {from.span()=>
234 {
235 let __ig_column: ::std::vec::Vec<_> = __ig_held
236 .iter()
237 .map(|__ig_row| #read)
238 .collect();
239 <#fold as #measure<_>>::fold(&#built, &__ig_column)
240 }
241 }
242 }
243 // THE ROWS: the fold reads no column, so the items ARE the group's rows. The item type is
244 // WRITTEN — `Counting` implements the trait at every type there is, so an inferred call over
245 // it is `E0282`.
246 (Owed::Nothing | Owed::Theirs, _) => {
247 quote_spanned!(at=> <#fold as #measure<&#upstream>>::fold(&#built, &__ig_held))
248 }
249 // Unreachable through the grammar: `Owed::Column` without a `from` is the entry the front end
250 // refuses by name. Spelled as the rows so a model built by hand still emits something that
251 // compiles or says why, rather than a `todo!` a reader has to trust nobody reaches.
252 (Owed::Column, None) => {
253 quote_spanned!(at=> <#fold as #measure<&#upstream>>::fold(&#built, &__ig_held))
254 }
255 };
256 quote_spanned!(at=> #field: #value,)
257 }
258
259 /// The TYPE a measure entry named — a shipped citizen through the shelf, or the path as written.
260 ///
261 /// The shorthand resolves HERE, which is the one place that knows where the shelf is. It is the
262 /// elected fold's own line one kind over, and both arms arrive at one construction.
263 fn citizen(&self, by: &Measure) -> TokenStream {
264 match by {
265 Measure::Counting => framework(&self.krate, &["measure"], "Counting"),
266 Measure::Summing => framework(&self.krate, &["measure"], "Summing"),
267 Measure::Declared(path) => quote_spanned!(path.span()=> #path),
268 }
269 }
270}
271
272/// READ ONE COLUMN out of an upstream row, by value.
273///
274/// The borrowing accessor and a clone, at the span of the STRING that named the column — so a
275/// column the upstream has not got is `E0599` where the author wrote its name rather than somewhere
276/// inside an expansion. `<field>_ref` is the one accessor every column has: `copy` ADDS `<field>()`
277/// beside it and renames nothing, which is what makes reading through the borrow safe whatever the
278/// upstream declared.
279///
280/// Fully qualified through the upstream's own path rather than as a method call, so the read cannot
281/// pick up an inherent method of some other type that happens to be in scope.
282fn read(upstream: &syn::Path, from: &syn::Ident) -> TokenStream {
283 let reader = format_ident!("{from}_ref", span = from.span());
284 quote_spanned!(from.span()=> ::core::clone::Clone::clone(#upstream::#reader(__ig_row)))
285}
286
287/// The upstream's path as the declaration wrote it, for a doc line.
288fn path_text(path: &syn::Path) -> String {
289 path
290 .segments
291 .iter()
292 .map(|segment| segment.ident.to_string())
293 .collect::<Vec<_>>()
294 .join("::")
295}