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                        out.insert(u);
71                    }
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
297pub struct RangeVirtualDepProvider;
298
299impl RangeVirtualDepProvider {
300    pub(crate) fn resolve_range<R: EvaluationContext>(
301        engine: &Engine<R>,
302        sheet_name: &str,
303        range: &formualizer_common::SheetRangeRef<'_>,
304    ) -> Option<ResolvedExtent> {
305        resolve_used_extent_with_fallback(
306            OpenRangeBounds {
307                start_row: range.start_row.map(|bound| bound.index + 1),
308                start_column: range.start_col.map(|bound| bound.index + 1),
309                end_row: range.end_row.map(|bound| bound.index + 1),
310                end_column: range.end_col.map(|bound| bound.index + 1),
311            },
312            ExtentPolicy::VirtualDependencyCompat {
313                fallback_row: None,
314                fallback_column: None,
315            },
316            || {
317                engine
318                    .sheet_bounds(sheet_name)
319                    .map(|_| engine.config.max_open_ended_rows)
320            },
321            || {
322                engine
323                    .sheet_bounds(sheet_name)
324                    .map(|_| engine.config.max_open_ended_cols)
325            },
326            |first, last| engine.used_rows_for_columns(sheet_name, first, last),
327            |first, last| engine.used_cols_for_rows(sheet_name, first, last),
328        )
329    }
330
331    #[cfg(any(test, feature = "legacy_oracle"))]
332    pub fn get_virtual_deps<R: EvaluationContext>(
333        engine: &Engine<R>,
334        v: VertexId,
335    ) -> Vec<VertexId> {
336        let mut deps = Vec::new();
337        if let Some(ranges) = engine.graph.get_range_dependencies(v) {
338            let current_sheet_id = engine.graph.get_vertex_sheet_id(v);
339            for r in ranges {
340                let sheet_id = match r.sheet {
341                    formualizer_common::SheetLocator::Id(id) => id,
342                    _ => current_sheet_id,
343                };
344                let sheet_name = engine.graph.sheet_name(sheet_id);
345
346                let Some(extent) = Self::resolve_range(engine, sheet_name, r) else {
347                    continue;
348                };
349                let sr = extent.start_row;
350                let sc = extent.start_column;
351                let er = extent.end_row;
352                let ec = extent.end_column;
353
354                if engine.graph.sheet_index(sheet_id).is_some() {
355                    let sr0 = sr.saturating_sub(1);
356                    let er0 = er.saturating_sub(1);
357                    let sc0 = sc.saturating_sub(1);
358                    let ec0 = ec.saturating_sub(1);
359                    for u in engine.graph.vertices_in_cols(sheet_id, sc0, ec0) {
360                        let Some(pc) = engine.graph.vertex_grid_addr(u) else {
361                            continue;
362                        };
363                        let row0 = pc.row();
364                        if row0 < sr0 || row0 > er0 {
365                            continue;
366                        }
367                        match engine.graph.get_vertex_kind(u) {
368                            VertexKind::FormulaScalar | VertexKind::FormulaArray => {
369                                if (engine.graph.is_dirty(u) || engine.graph.is_volatile(u))
370                                    && u != v
371                                {
372                                    deps.push(u);
373                                }
374                            }
375                            _ => {}
376                        }
377                    }
378                }
379            }
380        }
381        deps
382    }
383}
384
385pub struct VirtualDepBuilder<'a, R: EvaluationContext> {
386    engine: &'a Engine<R>,
387}
388
389impl<'a, R: EvaluationContext> VirtualDepBuilder<'a, R> {
390    pub fn new(engine: &'a Engine<R>) -> Self {
391        Self { engine }
392    }
393    /// Plan hints for `candidates`. Under `unified_authority` a compressed
394    /// range read is an ordinary static edge of the relation (R-1), so the
395    /// planner already orders every formula inside the range before its
396    /// reader; only dynamic readers get hints (design §8.2). Enumerating the
397    /// range members costs |readers| × |range formulas| hints (100M for
398    /// 1,000 SUMIFS over a 100k formula column), and resolving their used
399    /// extent at plan time caches it before same-pass spills commit.
400    pub fn build(
401        &self,
402        candidates: &[VertexId],
403    ) -> (
404        rustc_hash::FxHashMap<VertexId, Vec<VertexId>>,
405        Vec<VertexId>,
406    ) {
407        self.build_inner(candidates, false)
408    }
409
410    /// Legacy's hints, range members included: what the legacy scheduler
411    /// (the test oracle) needs, since its range stripes carry no edges.
412    pub fn build_with_range_members(
413        &self,
414        candidates: &[VertexId],
415    ) -> (
416        rustc_hash::FxHashMap<VertexId, Vec<VertexId>>,
417        Vec<VertexId>,
418    ) {
419        self.build_inner(candidates, true)
420    }
421
422    fn build_inner(
423        &self,
424        candidates: &[VertexId],
425        range_members: bool,
426    ) -> (
427        rustc_hash::FxHashMap<VertexId, Vec<VertexId>>,
428        Vec<VertexId>,
429    ) {
430        let mut vdeps: rustc_hash::FxHashMap<VertexId, Vec<VertexId>> =
431            rustc_hash::FxHashMap::default();
432        let augmented_vertices: Vec<VertexId> = Vec::new(); // Will be populated in Phase 3
433
434        for &v in candidates {
435            // Range members are legacy's hints (its stripes carry no
436            // scheduling edges): the oracle scheduler's input only.
437            #[cfg(any(test, feature = "legacy_oracle"))]
438            let mut deps = if range_members {
439                RangeVirtualDepProvider::get_virtual_deps(self.engine, v)
440            } else {
441                Vec::new()
442            };
443            #[cfg(not(any(test, feature = "legacy_oracle")))]
444            let mut deps = Vec::new();
445            // Under the authority a reader with an observed read set is
446            // planned from it (rdi_dyn, rectangle hints); the pre-probe is
447            // for first evaluations only (design §8.2).
448            let observed =
449                !range_members && self.engine.graph.authority_host().observed(v).is_some();
450            let dynamic_deps = if observed {
451                Vec::new()
452            } else {
453                DynamicRefVirtualDepProvider::get_virtual_deps(self.engine, v)
454            };
455
456            deps.extend(dynamic_deps);
457            deps.sort_unstable();
458            deps.dedup();
459
460            if !deps.is_empty() {
461                vdeps.insert(v, deps);
462            }
463        }
464
465        (vdeps, augmented_vertices)
466    }
467}
468
469pub struct DynamicRefVirtualDepProvider;
470
471impl DynamicRefVirtualDepProvider {
472    fn collect<R: EvaluationContext>(
473        engine: &Engine<R>,
474        v: VertexId,
475    ) -> (Vec<VertexId>, Vec<Region>) {
476        if !engine.graph.is_dynamic(v) {
477            return (Vec::new(), Vec::new());
478        }
479        let Some(view) = engine.graph.formula_view(v) else {
480            return (Vec::new(), Vec::new());
481        };
482        let sheet_id = engine.graph.get_vertex_sheet_id(v);
483        let sheet_name = engine.graph.sheet_name(sheet_id);
484        let collector = DynamicRefCollector::new(engine, sheet_name);
485        let cell_ref = engine
486            .graph
487            .get_cell_ref(v)
488            .unwrap_or_else(|| engine.graph.make_cell_ref(sheet_name, 0, 0));
489        let interpreter = Interpreter::new_with_cell(&collector, sheet_name, cell_ref);
490        let _ = interpreter.evaluate_formula_view(
491            view,
492            engine.graph.data_store(),
493            engine.graph.sheet_reg(),
494        );
495        let mut deps = collector
496            .collected
497            .lock()
498            .unwrap()
499            .iter()
500            .copied()
501            .filter(|&dependency| dependency != v)
502            .collect::<Vec<_>>();
503        deps.sort_unstable();
504        deps.dedup();
505        let mut regions = collector
506            .collected_regions
507            .lock()
508            .unwrap()
509            .iter()
510            .copied()
511            .collect::<Vec<_>>();
512        regions.sort_by_key(|region| {
513            let (rows, cols) = region.axis_ranges();
514            (region.sheet_id(), rows.query_bounds(), cols.query_bounds())
515        });
516        regions.dedup();
517        (deps, regions)
518    }
519
520    pub fn get_virtual_deps<R: EvaluationContext>(
521        engine: &Engine<R>,
522        v: VertexId,
523    ) -> Vec<VertexId> {
524        Self::collect(engine, v).0
525    }
526
527    pub(crate) fn get_virtual_regions<R: EvaluationContext>(
528        engine: &Engine<R>,
529        v: VertexId,
530    ) -> Vec<Region> {
531        Self::collect(engine, v).1
532    }
533}
formualizer_eval/engine/virtual_deps.rs

formualizer_eval/engine/
virtual_deps.rs
