formualizer_eval/engine/
virtual_deps.rs

1use crate::engine::VertexId;
2use crate::engine::VertexKind;
3use crate::engine::eval::Engine;
4use crate::engine::template::region::Region;
5use crate::engine::used_extent::{
6    ExtentPolicy, OpenRangeBounds, ResolvedExtent, resolve_used_extent_with_fallback,
7};
8use crate::traits::{
9    EvaluationContext, FunctionProvider, NamedRangeResolver, Range, RangeResolver,
10    ReferenceResolver, Resolver, SourceResolver, Table, TableResolver,
11};
12use formualizer_common::{ExcelError, LiteralValue};
13use formualizer_parse::parser::{ReferenceType, TableReference};
14use rustc_hash::FxHashSet;
15use std::sync::Mutex;
16
17use crate::interpreter::Interpreter;
18
19pub struct DynamicRefCollector<'a, R: EvaluationContext> {
20    pub engine: &'a Engine<R>,
21    pub current_sheet: &'a str,
22    pub(crate) collected: Mutex<FxHashSet<VertexId>>,
23    pub(crate) collected_regions: Mutex<FxHashSet<Region>>,
24}
25
26impl<'a, R: EvaluationContext> DynamicRefCollector<'a, R> {
27    pub fn new(engine: &'a Engine<R>, current_sheet: &'a str) -> Self {
28        Self {
29            engine,
30            current_sheet,
31            collected: Mutex::new(FxHashSet::default()),
32            collected_regions: Mutex::new(FxHashSet::default()),
33        }
34    }
35
36    fn collect_formula_vertices_in_rect(
37        &self,
38        sheet_name: &str,
39        sr: u32,
40        sc: u32,
41        er: u32,
42        ec: u32,
43    ) {
44        let Some(sheet_id) = self.engine.graph.sheet_id(sheet_name) else {
45            return;
46        };
47        let sr0 = sr.saturating_sub(1);
48        let er0 = er.saturating_sub(1);
49        let sc0 = sc.saturating_sub(1);
50        let ec0 = ec.saturating_sub(1);
51        self.collected_regions
52            .lock()
53            .unwrap()
54            .insert(Region::rect(sheet_id, sr0, er0, sc0, ec0).normalized());
55        if self.engine.graph.sheet_index(sheet_id).is_none() {
56            return;
57        }
58
59        let mut out = self.collected.lock().unwrap();
60        for u in self.engine.graph.vertices_in_cols(sheet_id, sc0, ec0) {
61            let Some(row0) = self.engine.graph.vertex_grid_addr(u).map(|addr| addr.row()) else {
62                continue;
63            };
64            if row0 < sr0 || row0 > er0 {
65                continue;
66            }
67            match self.engine.graph.get_vertex_kind(u) {
68                VertexKind::FormulaScalar | VertexKind::FormulaArray
69                    if (self.engine.graph.is_dirty(u) || self.engine.graph.is_volatile(u)) =>
70                {
71                    out.insert(u);
72                }
73                _ => {}
74            }
75        }
76    }
77
78    fn collect_formula_vertices_for_range(
79        &self,
80        sheet_name: &str,
81        start_row: Option<u32>,
82        start_col: Option<u32>,
83        end_row: Option<u32>,
84        end_col: Option<u32>,
85    ) {
86        let Some(extent) = resolve_used_extent_with_fallback(
87            OpenRangeBounds {
88                start_row,
89                start_column: start_col,
90                end_row,
91                end_column: end_col,
92            },
93            ExtentPolicy::EvaluationCompat {
94                fallback_row: None,
95                fallback_column: None,
96            },
97            || {
98                self.engine
99                    .sheet_bounds(sheet_name)
100                    .map(|_| self.engine.config.max_open_ended_rows)
101            },
102            || {
103                self.engine
104                    .sheet_bounds(sheet_name)
105                    .map(|_| self.engine.config.max_open_ended_cols)
106            },
107            |first, last| self.engine.used_rows_for_columns(sheet_name, first, last),
108            |first, last| self.engine.used_cols_for_rows(sheet_name, first, last),
109        ) else {
110            return;
111        };
112
113        self.collect_formula_vertices_in_rect(
114            sheet_name,
115            extent.start_row,
116            extent.start_column,
117            extent.end_row,
118            extent.end_column,
119        );
120    }
121}
122
123impl<'a, R: EvaluationContext> ReferenceResolver for DynamicRefCollector<'a, R> {
124    fn resolve_cell_reference(
125        &self,
126        sheet: Option<&str>,
127        row: u32,
128        col: u32,
129    ) -> Result<LiteralValue, ExcelError> {
130        let sheet_name = sheet.unwrap_or(self.current_sheet);
131        if let Some(sheet_id) = self.engine.graph.sheet_id(sheet_name) {
132            self.collected_regions.lock().unwrap().insert(Region::point(
133                sheet_id,
134                row.saturating_sub(1),
135                col.saturating_sub(1),
136            ));
137        }
138        if let Some(vid) = self
139            .engine
140            .graph
141            .get_vertex_id_for_address(&self.engine.graph.make_cell_ref(sheet_name, row, col))
142        {
143            self.collected.lock().unwrap().insert(vid);
144        }
145        self.engine.resolve_cell_reference(sheet, row, col)
146    }
147}
148
149impl<'a, R: EvaluationContext> RangeResolver for DynamicRefCollector<'a, R> {
150    fn resolve_range_reference(
151        &self,
152        sheet: Option<&str>,
153        sr: Option<u32>,
154        sc: Option<u32>,
155        er: Option<u32>,
156        ec: Option<u32>,
157    ) -> Result<Box<dyn Range>, ExcelError> {
158        let sheet_name = sheet.unwrap_or(self.current_sheet);
159        self.collect_formula_vertices_for_range(sheet_name, sr, sc, er, ec);
160        self.engine.resolve_range_reference(sheet, sr, sc, er, ec)
161    }
162}
163
164impl<'a, R: EvaluationContext> NamedRangeResolver for DynamicRefCollector<'a, R> {
165    fn resolve_named_range_reference(
166        &self,
167        name: &str,
168    ) -> Result<Vec<Vec<LiteralValue>>, ExcelError> {
169        self.engine.resolve_named_range_reference(name)
170    }
171}
172
173impl<'a, R: EvaluationContext> TableResolver for DynamicRefCollector<'a, R> {
174    fn resolve_table_reference(&self, tref: &TableReference) -> Result<Box<dyn Table>, ExcelError> {
175        self.engine.resolve_table_reference(tref)
176    }
177}
178
179impl<'a, R: EvaluationContext> SourceResolver for DynamicRefCollector<'a, R> {
180    fn source_scalar_version(&self, name: &str) -> Option<u64> {
181        self.engine.source_scalar_version(name)
182    }
183    fn resolve_source_scalar(&self, name: &str) -> Result<LiteralValue, ExcelError> {
184        self.engine.resolve_source_scalar(name)
185    }
186    fn source_table_version(&self, name: &str) -> Option<u64> {
187        self.engine.source_table_version(name)
188    }
189    fn resolve_source_table(&self, name: &str) -> Result<Box<dyn Table>, ExcelError> {
190        self.engine.resolve_source_table(name)
191    }
192}
193
194impl<'a, R: EvaluationContext> Resolver for DynamicRefCollector<'a, R> {}
195
196impl<'a, R: EvaluationContext> FunctionProvider for DynamicRefCollector<'a, R> {
197    fn planning_semantic_revision(&self) -> Option<u64> {
198        self.engine.planning_semantic_revision()
199    }
200
201    fn get_function(
202        &self,
203        ns: &str,
204        name: &str,
205    ) -> Option<std::sync::Arc<dyn crate::traits::Function>> {
206        self.engine.get_function(ns, name)
207    }
208
209    fn get_function_for_planning(
210        &self,
211        ns: &str,
212        name: &str,
213    ) -> Option<std::sync::Arc<dyn crate::traits::Function>> {
214        self.engine.get_function_for_planning(ns, name)
215    }
216}
217
218impl<'a, R: EvaluationContext> EvaluationContext for DynamicRefCollector<'a, R> {
219    fn cancellation_token(&self) -> Option<crate::engine::CancelToken> {
220        self.engine.cancellation_token()
221    }
222
223    fn resolve_cell_format(
224        &self,
225        sheet: Option<&str>,
226        row: u32,
227        col: u32,
228        current_sheet: &str,
229    ) -> Option<crate::format::FormatId> {
230        self.engine
231            .resolve_cell_format(sheet, row, col, current_sheet)
232    }
233
234    fn format_class(
235        &self,
236        format: crate::format::FormatId,
237    ) -> Option<formualizer_common::numfmt::FormatClass> {
238        self.engine.format_class(format)
239    }
240
241    fn record_cell_derived_format(
242        &self,
243        sheet: &str,
244        row: u32,
245        col: u32,
246        format: Option<crate::format::FormatId>,
247    ) {
248        self.engine
249            .record_cell_derived_format(sheet, row, col, format)
250    }
251
252    fn resolve_range_view<'c>(
253        &'c self,
254        reference: &ReferenceType,
255        current_sheet: &str,
256    ) -> Result<crate::engine::range_view::RangeView<'c>, ExcelError> {
257        // Collect vertices directly
258        match reference {
259            ReferenceType::Cell {
260                sheet, row, col, ..
261            } => {
262                let sheet_name = sheet.as_deref().unwrap_or(current_sheet);
263                self.collect_formula_vertices_in_rect(sheet_name, *row, *col, *row, *col);
264            }
265            ReferenceType::Range {
266                sheet,
267                start_row,
268                start_col,
269                end_row,
270                end_col,
271                ..
272            } => {
273                let sheet_name = sheet.as_deref().unwrap_or(current_sheet);
274                self.collect_formula_vertices_for_range(
275                    sheet_name, *start_row, *start_col, *end_row, *end_col,
276                );
277            }
278            ReferenceType::NamedRange(name) => {
279                let sid = self.engine.sheet_id(current_sheet);
280                if let Some(s) = sid
281                    && let Some(nr) = self.engine.graph.resolve_name_entry(name, s)
282                {
283                    let vid = nr.vertex;
284                    self.collected.lock().unwrap().insert(vid);
285                }
286            }
287            ReferenceType::Table(_) => {
288                // Table references might be tricky, skip for now or resolve from graph if possible
289            }
290            _ => {}
291        }
292
293        self.engine.resolve_range_view(reference, current_sheet)
294    }
295
296    fn resolve_spill_reference(
297        &self,
298        anchor: &ReferenceType,
299        current_sheet: &str,
300    ) -> Result<ReferenceType, ExcelError> {
301        // The anchor is a dependency whether or not it currently spills.
302        match anchor {
303            ReferenceType::Cell {
304                sheet, row, col, ..
305            } => {
306                let sheet_name = sheet.as_deref().unwrap_or(current_sheet);
307                self.collect_formula_vertices_in_rect(sheet_name, *row, *col, *row, *col);
308            }
309            ReferenceType::NamedRange(name) => {
310                if let Some(sheet_id) = self.engine.sheet_id(current_sheet)
311                    && let Some(named) = self.engine.graph.resolve_name_entry(name, sheet_id)
312                {
313                    self.collected.lock().unwrap().insert(named.vertex);
314                }
315            }
316            _ => {}
317        }
318        self.engine.resolve_spill_reference(anchor, current_sheet)
319    }
320}
321
322pub struct RangeVirtualDepProvider;
323
324impl RangeVirtualDepProvider {
325    pub(crate) fn resolve_range<R: EvaluationContext>(
326        engine: &Engine<R>,
327        sheet_name: &str,
328        range: &formualizer_common::SheetRangeRef<'_>,
329    ) -> Option<ResolvedExtent> {
330        resolve_used_extent_with_fallback(
331            OpenRangeBounds {
332                start_row: range.start_row.map(|bound| bound.index + 1),
333                start_column: range.start_col.map(|bound| bound.index + 1),
334                end_row: range.end_row.map(|bound| bound.index + 1),
335                end_column: range.end_col.map(|bound| bound.index + 1),
336            },
337            ExtentPolicy::VirtualDependencyCompat {
338                fallback_row: None,
339                fallback_column: None,
340            },
341            || {
342                engine
343                    .sheet_bounds(sheet_name)
344                    .map(|_| engine.config.max_open_ended_rows)
345            },
346            || {
347                engine
348                    .sheet_bounds(sheet_name)
349                    .map(|_| engine.config.max_open_ended_cols)
350            },
351            |first, last| engine.used_rows_for_columns(sheet_name, first, last),
352            |first, last| engine.used_cols_for_rows(sheet_name, first, last),
353        )
354    }
355
356    #[cfg(any(test, feature = "legacy_oracle"))]
357    pub fn get_virtual_deps<R: EvaluationContext>(
358        engine: &Engine<R>,
359        v: VertexId,
360    ) -> Vec<VertexId> {
361        let mut deps = Vec::new();
362        if let Some(ranges) = engine.graph.get_range_dependencies(v) {
363            let current_sheet_id = engine.graph.get_vertex_sheet_id(v);
364            for r in ranges {
365                let sheet_id = match r.sheet {
366                    formualizer_common::SheetLocator::Id(id) => id,
367                    _ => current_sheet_id,
368                };
369                let sheet_name = engine.graph.sheet_name(sheet_id);
370
371                let Some(extent) = Self::resolve_range(engine, sheet_name, r) else {
372                    continue;
373                };
374                let sr = extent.start_row;
375                let sc = extent.start_column;
376                let er = extent.end_row;
377                let ec = extent.end_column;
378
379                if engine.graph.sheet_index(sheet_id).is_some() {
380                    let sr0 = sr.saturating_sub(1);
381                    let er0 = er.saturating_sub(1);
382                    let sc0 = sc.saturating_sub(1);
383                    let ec0 = ec.saturating_sub(1);
384                    for u in engine.graph.vertices_in_cols(sheet_id, sc0, ec0) {
385                        let Some(pc) = engine.graph.vertex_grid_addr(u) else {
386                            continue;
387                        };
388                        let row0 = pc.row();
389                        if row0 < sr0 || row0 > er0 {
390                            continue;
391                        }
392                        match engine.graph.get_vertex_kind(u) {
393                            VertexKind::FormulaScalar | VertexKind::FormulaArray
394                                if (engine.graph.is_dirty(u) || engine.graph.is_volatile(u))
395                                    && u != v =>
396                            {
397                                deps.push(u);
398                            }
399                            _ => {}
400                        }
401                    }
402                }
403            }
404        }
405        deps
406    }
407}
408
409pub struct VirtualDepBuilder<'a, R: EvaluationContext> {
410    engine: &'a Engine<R>,
411}
412
413impl<'a, R: EvaluationContext> VirtualDepBuilder<'a, R> {
414    pub fn new(engine: &'a Engine<R>) -> Self {
415        Self { engine }
416    }
417    /// Plan hints for `candidates`. Under `unified_authority` a compressed
418    /// range read is an ordinary static edge of the relation (R-1), so the
419    /// planner already orders every formula inside the range before its
420    /// reader; only dynamic readers get hints (design §8.2). Enumerating the
421    /// range members costs |readers| × |range formulas| hints (100M for
422    /// 1,000 SUMIFS over a 100k formula column), and resolving their used
423    /// extent at plan time caches it before same-pass spills commit.
424    pub fn build(
425        &self,
426        candidates: &[VertexId],
427    ) -> (
428        rustc_hash::FxHashMap<VertexId, Vec<VertexId>>,
429        Vec<VertexId>,
430    ) {
431        self.build_inner(candidates, false)
432    }
433
434    /// Legacy's hints, range members included: what the legacy scheduler
435    /// (the test oracle) needs, since its range stripes carry no edges.
436    pub fn build_with_range_members(
437        &self,
438        candidates: &[VertexId],
439    ) -> (
440        rustc_hash::FxHashMap<VertexId, Vec<VertexId>>,
441        Vec<VertexId>,
442    ) {
443        self.build_inner(candidates, true)
444    }
445
446    fn build_inner(
447        &self,
448        candidates: &[VertexId],
449        range_members: bool,
450    ) -> (
451        rustc_hash::FxHashMap<VertexId, Vec<VertexId>>,
452        Vec<VertexId>,
453    ) {
454        let mut vdeps: rustc_hash::FxHashMap<VertexId, Vec<VertexId>> =
455            rustc_hash::FxHashMap::default();
456        let augmented_vertices: Vec<VertexId> = Vec::new(); // Will be populated in Phase 3
457
458        for &v in candidates {
459            // Range members are legacy's hints (its stripes carry no
460            // scheduling edges): the oracle scheduler's input only.
461            #[cfg(any(test, feature = "legacy_oracle"))]
462            let mut deps = if range_members {
463                RangeVirtualDepProvider::get_virtual_deps(self.engine, v)
464            } else {
465                Vec::new()
466            };
467            #[cfg(not(any(test, feature = "legacy_oracle")))]
468            let mut deps = Vec::new();
469            // Under the authority a reader with an observed read set is
470            // planned from it (rdi_dyn, rectangle hints); the pre-probe is
471            // for first evaluations only (design §8.2).
472            let observed =
473                !range_members && self.engine.graph.authority_host().observed(v).is_some();
474            let dynamic_deps = if observed {
475                Vec::new()
476            } else {
477                DynamicRefVirtualDepProvider::get_virtual_deps(self.engine, v)
478            };
479
480            deps.extend(dynamic_deps);
481            deps.sort_unstable();
482            deps.dedup();
483
484            if !deps.is_empty() {
485                vdeps.insert(v, deps);
486            }
487        }
488
489        (vdeps, augmented_vertices)
490    }
491}
492
493pub struct DynamicRefVirtualDepProvider;
494
495impl DynamicRefVirtualDepProvider {
496    fn collect<R: EvaluationContext>(
497        engine: &Engine<R>,
498        v: VertexId,
499    ) -> (Vec<VertexId>, Vec<Region>) {
500        if !engine.graph.is_dynamic(v) {
501            return (Vec::new(), Vec::new());
502        }
503        let Some(view) = engine.graph.formula_view(v) else {
504            return (Vec::new(), Vec::new());
505        };
506        let sheet_id = engine.graph.get_vertex_sheet_id(v);
507        let sheet_name = engine.graph.sheet_name(sheet_id);
508        let collector = DynamicRefCollector::new(engine, sheet_name);
509        let cell_ref = engine
510            .graph
511            .get_cell_ref(v)
512            .unwrap_or_else(|| engine.graph.make_cell_ref(sheet_name, 0, 0));
513        let interpreter = Interpreter::new_with_cell(&collector, sheet_name, cell_ref);
514        let _ = interpreter.evaluate_formula_view(
515            view,
516            engine.graph.data_store(),
517            engine.graph.sheet_reg(),
518        );
519        let mut deps = collector
520            .collected
521            .lock()
522            .unwrap()
523            .iter()
524            .copied()
525            .filter(|&dependency| dependency != v)
526            .collect::<Vec<_>>();
527        deps.sort_unstable();
528        deps.dedup();
529        let mut regions = collector
530            .collected_regions
531            .lock()
532            .unwrap()
533            .iter()
534            .copied()
535            .collect::<Vec<_>>();
536        regions.sort_by_key(|region| {
537            let (rows, cols) = region.axis_ranges();
538            (region.sheet_id(), rows.query_bounds(), cols.query_bounds())
539        });
540        regions.dedup();
541        (deps, regions)
542    }
543
544    pub fn get_virtual_deps<R: EvaluationContext>(
545        engine: &Engine<R>,
546        v: VertexId,
547    ) -> Vec<VertexId> {
548        Self::collect(engine, v).0
549    }
550
551    pub(crate) fn get_virtual_regions<R: EvaluationContext>(
552        engine: &Engine<R>,
553        v: VertexId,
554    ) -> Vec<Region> {
555        Self::collect(engine, v).1
556    }
557}
formualizer_eval/engine/virtual_deps.rs

formualizer_eval/engine/
virtual_deps.rs
