Struct Engine 

pub struct Engine<R> {
    pub config: EvalConfig,
    pub recalc_epoch: u64,
    /* private fields */
}

Fields

config: EvalConfig

recalc_epoch: u64

Implementations

impl<R> Engine<R>

where R: EvaluationContext,

pub fn new(resolver: R, config: EvalConfig) -> Self

Panics

Panics when config.cycle is invalid ([CycleConfig::validate], spec §2): Iterate with detection: Static, max_iterations == 0, or a negative/non-finite max_change. EvalConfig::with_cycle rejects these at build; this re-validates configs assembled via struct literals.

pub fn with_thread_pool( resolver: R, config: EvalConfig, thread_pool: Arc<ThreadPool>, ) -> Self

Create an Engine with a custom thread pool (for shared thread pool scenarios)

Panics

Panics when config.cycle is invalid, exactly like Engine::new.

pub fn workbook_load_limits(&self) -> &WorkbookLoadLimits

pub fn set_workbook_load_limits(&mut self, limits: WorkbookLoadLimits)

pub fn last_virtual_dep_telemetry(&self) -> &VirtualDepTelemetry

pub fn last_cycle_telemetry(&self) -> &CycleTelemetry

Telemetry from Runtime SCC evaluation during the most recent evaluation request (always default-zero under CycleDetection::Static or when enable_virtual_dep_telemetry is off).

pub fn virtual_dep_fallback_activations(&self) -> u64

pub fn default_sheet_id(&self) -> SheetId

pub fn default_sheet_name(&self) -> &str

pub fn set_workbook_seed(&mut self, seed: u64)

Update the workbook seed for deterministic RNGs in functions.

pub fn set_volatile_level(&mut self, level: VolatileLevel)

Set the volatile level policy (Always/OnRecalc/OnOpen)

pub fn set_deterministic_mode( &mut self, mode: DeterministicMode, ) -> Result<(), ExcelError>

Enable/disable deterministic evaluation mode (fixed clock + timezone).

pub fn set_clock(&mut self, clock: Arc<dyn ClockProvider>)

Inject a custom ClockProvider for volatile date/time builtins (NOW(), TODAY()).

The provider is the clock source; per spec §7.11 the engine samples it once at the start of every evaluation request and all reads within that recalc (including SCC iteration passes) observe the frozen sample.

pub fn sheet_id(&self, name: &str) -> Option<SheetId>

pub fn sheet_id_mut(&mut self, name: &str) -> SheetId

pub fn sheet_name(&self, id: SheetId) -> &str

pub fn add_sheet(&mut self, name: &str) -> Result<SheetId, ExcelError>

pub fn duplicate_sheet( &mut self, source: &str, new_name: &str, ) -> Result<SheetId, ExcelError>

pub fn remove_sheet(&mut self, sheet_id: SheetId) -> Result<(), ExcelError>

pub fn rename_sheet( &mut self, sheet_id: SheetId, new_name: &str, ) -> Result<(), ExcelError>

pub fn named_ranges_iter(&self) -> impl Iterator<Item = (&String, &NamedRange)>

pub fn sheet_named_ranges_iter( &self, ) -> impl Iterator<Item = (&(SheetId, String), &NamedRange)>

pub fn resolve_name_entry( &self, name: &str, current_sheet: SheetId, ) -> Option<&NamedRange>

pub fn named_ranges_snapshot(&self) -> Vec<NamedRangeSnapshot>

pub fn named_ranges_snapshot_for_sheet( &self, sheet_id: SheetId, ) -> Vec<NamedRangeSnapshot>

pub fn define_name( &mut self, name: &str, definition: NamedDefinition, scope: NameScope, ) -> Result<(), ExcelError>

pub fn update_name( &mut self, name: &str, definition: NamedDefinition, scope: NameScope, ) -> Result<(), ExcelError>

pub fn delete_name( &mut self, name: &str, scope: NameScope, ) -> Result<(), ExcelError>

pub fn define_table( &mut self, name: &str, range: RangeRef, header_row: bool, headers: Vec<String>, totals_row: bool, ) -> Result<(), ExcelError>

pub fn define_source_scalar( &mut self, name: &str, version: Option<u64>, ) -> Result<(), ExcelError>

pub fn define_source_table( &mut self, name: &str, version: Option<u64>, ) -> Result<(), ExcelError>

pub fn set_source_scalar_version( &mut self, name: &str, version: Option<u64>, ) -> Result<(), ExcelError>

pub fn set_source_table_version( &mut self, name: &str, version: Option<u64>, ) -> Result<(), ExcelError>

pub fn invalidate_source(&mut self, name: &str) -> Result<(), ExcelError>

pub fn vertex_value(&self, vertex: VertexId) -> Option<LiteralValue>

pub fn graph_cell_value( &self, sheet: &str, row: u32, col: u32, ) -> Option<LiteralValue>

pub fn vertex_for_cell(&self, cell: &CellRef) -> Option<VertexId>

pub fn evaluation_vertices(&self) -> Vec<VertexId>

pub fn baseline_stats(&self) -> EngineBaselineStats

Return read-only baseline counters for FormulaPlane/dispatch benchmarking.

pub fn set_first_load_assume_new(&mut self, enabled: bool)

pub fn reset_ensure_touched(&mut self)

pub fn finalize_sheet_index(&mut self, sheet: &str)

pub fn action<T>( &mut self, name: impl AsRef<str>, f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, EditorError>, ) -> Result<T, EditorError>

Execute a named Engine action.

Ticket 614 introduces this as the stable Engine-level transaction surface. For now actions are commit-only: they do not create changelog boundaries and they do not provide rollback/atomicity.

Nested actions are deterministically handled by disallowing nesting: calling Engine::action while another action is active returns EditorError::TransactionFailed.

pub fn action_atomic<T>( &mut self, name: impl Into<String>, f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, EditorError>, ) -> Result<T, EditorError>

Execute a named Engine action with atomic commit/rollback semantics.

This variant does not require a ChangeLog and uses an internal journal for rollback.

pub fn action_atomic_journal<T>( &mut self, name: impl Into<String>, f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, EditorError>, ) -> Result<(T, ActionJournal), EditorError>

Like action_atomic, but returns the committed journal entry for undo/redo storage.

pub fn action_with_logger<T>( &mut self, log: &mut ChangeLog, name: impl AsRef<str>, f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, EditorError>, ) -> Result<T, EditorError>

Execute a named Engine action, logging graph changes into the provided ChangeLog.

Ticket 615: this variant provides atomicity. If the action returns an error, it rolls back:

• Dependency graph structural edits (via inverse ChangeEvents)
• Arrow-truth overlay writes mirrored from ChangeEvents
• ChangeLog entries (truncated back to the pre-action length)

pub fn edit_with_logger<T>( &mut self, log: &mut ChangeLog, f: impl FnOnce(&mut VertexEditor<'_>) -> T, ) -> T

pub fn undo_logged( &mut self, undo: &mut UndoEngine, log: &mut ChangeLog, ) -> Result<(), EditorError>

pub fn redo_logged( &mut self, undo: &mut UndoEngine, log: &mut ChangeLog, ) -> Result<(), EditorError>

pub fn undo_action(&mut self, undo: &mut UndoEngine) -> Result<(), EditorError>

Undo the last committed atomic action using the journal stack.

This path does not require a ChangeLog.

pub fn redo_action(&mut self, undo: &mut UndoEngine) -> Result<(), EditorError>

Redo the last undone atomic action using the journal stack.

This path does not require a ChangeLog.

pub fn set_default_sheet_by_name(&mut self, name: &str)

pub fn set_default_sheet_by_id(&mut self, id: SheetId)

pub fn set_sheet_index_mode(&mut self, mode: SheetIndexMode)

pub fn mark_data_edited(&mut self)

Mark data edited: bump snapshot and set edited flag. Value-only edits keep the stable-topology schedule cache alive.

pub fn mark_topology_edited(&mut self)

Mark a topology-changing edit: bump snapshot + topology epoch and invalidate cached schedules.

pub fn sheet_store(&self) -> &SheetStore

Access Arrow sheet store (read-only)

pub fn sheet_store_mut(&mut self) -> &mut SheetStore

Access Arrow sheet store (mutable)

pub fn has_staged_formulas(&self) -> bool

pub fn staged_formula_count(&self) -> usize

pub fn stage_formula_text( &mut self, sheet: &str, row: u32, col: u32, text: String, )

Stage a formula text instead of inserting into the graph (used when deferring is enabled).

pub fn clear_staged_formula_text( &mut self, sheet: &str, row: u32, col: u32, ) -> Option<String>

pub fn clear_staged_formulas_for_sheet(&mut self, sheet: &str)

pub fn rename_staged_formula_sheet(&mut self, old: &str, new: &str)

pub fn get_staged_formula_text( &self, sheet: &str, row: u32, col: u32, ) -> Option<String>

Get a staged formula text for a given cell if present (cloned).

pub fn formula_parse_diagnostics(&self) -> &[FormulaParseDiagnostic]

pub fn take_formula_parse_diagnostics(&mut self) -> Vec<FormulaParseDiagnostic>

pub fn clear_formula_parse_diagnostics(&mut self)

pub fn last_formula_ingest_report(&self) -> Option<&FormulaIngestReport>

pub fn formula_ingest_report_total(&self) -> &FormulaIngestReport

pub fn ingest_formula_batches( &mut self, batches: Vec<FormulaIngestBatch>, ) -> Result<FormulaIngestReport, ExcelError>

pub fn handle_formula_parse_error( &mut self, sheet: &str, row: u32, col: u32, formula: &str, message: String, ) -> Result<Option<ASTNode>, ExcelError>

pub fn build_graph_all(&mut self) -> Result<(), ExcelError>

Build graph for all staged formulas.

pub fn build_graph_for_sheets<'a, I: IntoIterator<Item = &'a str>>( &mut self, sheets: I, ) -> Result<(), ExcelError>

Build graph for specific sheets (consuming only those staged entries).

pub fn begin_bulk_ingest_arrow(&mut self) -> ArrowBulkIngestBuilder<'_, R>

Begin bulk Arrow ingest for base values (Phase A)

pub fn begin_bulk_update_arrow(&mut self) -> ArrowBulkUpdateBuilder<'_, R>

Begin bulk updates to Arrow store (Phase C)

pub fn set_row_hidden( &mut self, sheet: &str, row_1based: u32, hidden: bool, source: RowVisibilitySource, ) -> Result<(), EditorError>

pub fn set_rows_hidden( &mut self, sheet: &str, start_row_1based: u32, end_row_1based: u32, hidden: bool, source: RowVisibilitySource, ) -> Result<(), EditorError>

pub fn is_row_hidden( &self, sheet: &str, row_1based: u32, source: Option<RowVisibilitySource>, ) -> Option<bool>

pub fn row_visibility_version(&self, sheet: &str) -> Option<u64>

pub fn insert_rows( &mut self, sheet: &str, before: u32, count: u32, ) -> Result<ShiftSummary, EditorError>

Insert rows (1-based) and mirror into Arrow store when enabled

pub fn delete_rows( &mut self, sheet: &str, start: u32, count: u32, ) -> Result<ShiftSummary, EditorError>

Delete rows (1-based) and mirror into Arrow store when enabled

pub fn insert_columns( &mut self, sheet: &str, before: u32, count: u32, ) -> Result<ShiftSummary, EditorError>

Insert columns (1-based) and mirror into Arrow store when enabled

pub fn delete_columns( &mut self, sheet: &str, start: u32, count: u32, ) -> Result<ShiftSummary, EditorError>

Delete columns (1-based) and mirror into Arrow store when enabled

pub fn overlay_memory_usage(&self) -> usize

Estimated memory usage for computed overlays (formula/spill mirroring).

pub fn set_cell_value( &mut self, sheet: &str, row: u32, col: u32, value: LiteralValue, ) -> Result<(), ExcelError>

Set a cell value

pub fn set_cell_value_ref( &mut self, cell: SheetCellRef<'_>, current_sheet: &str, value: LiteralValue, ) -> Result<(), ExcelError>

pub fn set_cell_formula_ref( &mut self, cell: SheetCellRef<'_>, current_sheet: &str, ast: ASTNode, ) -> Result<(), ExcelError>

pub fn get_cell_value_ref( &self, cell: SheetCellRef<'_>, current_sheet: &str, ) -> Result<Option<LiteralValue>, ExcelError>

pub fn resolve_range_view_sheet_ref<'c>( &'c self, r: &SheetRef<'_>, current_sheet: &str, ) -> Result<RangeView<'c>, ExcelError>

pub fn set_cell_formula( &mut self, sheet: &str, row: u32, col: u32, ast: ASTNode, ) -> Result<(), ExcelError>

Set a cell formula

pub fn bulk_set_formulas<I>( &mut self, sheet: &str, items: I, ) -> Result<usize, ExcelError>

where I: IntoIterator<Item = (u32, u32, ASTNode)>,

Bulk set many formulas on a sheet. Skips per-cell snapshot bumping and minimizes edge rebuilds.

pub fn get_cell_value( &self, sheet: &str, row: u32, col: u32, ) -> Option<LiteralValue>

Get a cell value

pub fn get_cell( &self, sheet: &str, row: u32, col: u32, ) -> Option<(Option<ASTNode>, Option<LiteralValue>)>

Get formula AST (if any) and current stored value for a cell

pub fn begin_batch(&mut self)

Begin batch operations - defer CSR rebuilds for better performance

pub fn end_batch(&mut self)

End batch operations and trigger CSR rebuild

pub fn begin_deferred_dirty(&mut self)

Begin a deferred-dirty scope for a multi-edit batch: while active, every edit’s dirty propagation queues its sources instead of running a full BFS per edit, and the outermost end_deferred_dirty flushes the union with ONE multi-source propagation (O(component) instead of O(edits × component)). See DependencyGraph::begin_deferred_dirty.

Callers MUST run end_deferred_dirty on every exit path, including error returns; evaluation entry points debug_assert no scope leaked.

pub fn end_deferred_dirty(&mut self)

End a deferred-dirty scope, flushing the queued propagation when the outermost scope closes. See Engine::begin_deferred_dirty.

pub fn dirty_propagation_visits(&self) -> u64

Total vertices processed by dirty-propagation BFS loops since graph creation. Perf-shape observability only (cross-crate tests assert batched edits propagate O(component), not O(edits × component)).

pub fn evaluate_vertex( &mut self, vertex_id: VertexId, ) -> Result<LiteralValue, ExcelError>

pub fn evaluate_until( &mut self, targets: &[(&str, u32, u32)], ) -> Result<EvalResult, ExcelError>

Evaluate only the necessary precedents for specific target cells (demand-driven)

pub fn build_recalc_plan(&self) -> Result<RecalcPlan, ExcelError>

Build a reusable evaluation plan that covers every formula vertex in the workbook.

pub fn evaluate_recalc_plan( &mut self, plan: &RecalcPlan, ) -> Result<EvalResult, ExcelError>

Evaluate using a previously constructed plan. This avoids rebuilding layer schedules for each run.

impl<R> Engine<R>

where R: EvaluationContext,

pub fn evaluate_all(&mut self) -> Result<EvalResult, ExcelError>

Evaluate all dirty/volatile vertices

pub fn evaluate_all_with_delta( &mut self, ) -> Result<(EvalResult, EvalDelta), ExcelError>

pub fn evaluate_cell( &mut self, sheet: &str, row: u32, col: u32, ) -> Result<Option<LiteralValue>, ExcelError>

Convenience: demand-driven evaluation of a single cell by sheet name and row/col.

This will evaluate only the minimal set of dirty / volatile precedents required to bring the target cell up-to-date (as if a user asked for that single value), rather than scheduling a full workbook recalc. If the cell is already clean and non-volatile, no vertices will be recomputed.

Returns the (possibly newly computed) value stored for the cell afterwards. Empty cells return None. Errors are surfaced via the Result type.

pub fn evaluate_cells( &mut self, targets: &[(&str, u32, u32)], ) -> Result<Vec<Option<LiteralValue>>, ExcelError>

Convenience: demand-driven evaluation of multiple cells; accepts a slice of (sheet, row, col) triples. The union of required dirty / volatile precedents is computed once and evaluated, which is typically faster than calling evaluate_cell repeatedly for a related set of targets.

Returns the resulting values for each requested target in the same order.

pub fn evaluate_cells_cancellable( &mut self, targets: &[(&str, u32, u32)], cancel_flag: Arc<AtomicBool>, ) -> Result<Vec<Option<LiteralValue>>, ExcelError>

pub fn evaluate_cells_with_delta( &mut self, targets: &[(&str, u32, u32)], ) -> Result<(Vec<Option<LiteralValue>>, EvalDelta), ExcelError>

pub fn get_eval_plan( &self, targets: &[(&str, u32, u32)], ) -> Result<EvalPlan, ExcelError>

Get the evaluation plan for target cells without actually evaluating them

pub fn evaluate_all_cancellable( &mut self, cancel_flag: Arc<AtomicBool>, ) -> Result<EvalResult, ExcelError>

Evaluate all dirty/volatile vertices with cancellation support

pub fn evaluate_until_cancellable( &mut self, targets: &[&str], cancel_flag: Arc<AtomicBool>, ) -> Result<EvalResult, ExcelError>

Evaluate only the necessary precedents for specific target cells with cancellation support

pub fn thread_pool(&self) -> Option<&Arc<ThreadPool>>

Get access to the shared thread pool for parallel evaluation

impl<R> Engine<R>

where R: EvaluationContext,

pub fn evaluate_all_logged( &mut self, log: &mut ChangeLog, ) -> Result<EvalResult, ExcelError>

Evaluate all dirty/volatile vertices, recording effects into a ChangeLog.

This is the same flow as evaluate_all but threads a ChangeLog through every effect application so that spill commits/clears are captured.

impl<R: EvaluationContext> Engine<R>

pub fn begin_bulk_ingest(&mut self) -> BulkIngestBuilder<'_>

pub fn intern_formula_ast(&mut self, ast: &ASTNode) -> AstNodeId

Trait Implementations

impl<R> EvaluationContext for Engine<R>

where R: EvaluationContext,

fn resolve_range_view<'c>( &'c self, reference: &ReferenceType, current_sheet: &str, ) -> Result<RangeView<'c>, ExcelError>

New: resolve a reference into a RangeView (Phase 2 API)

fn clock(&self) -> &dyn ClockProvider

Clock provider for volatile date/time builtins.

fn thread_pool(&self) -> Option<&Arc<ThreadPool>>

Get access to the shared thread pool for parallel evaluation Returns None if parallel evaluation is disabled or unavailable

fn cancellation_token(&self) -> Option<Arc<AtomicBool>>

Optional cancellation token. When Some, long-running operations should periodically abort.

fn chunk_hint(&self) -> Option<usize>

Optional chunk size hint for streaming visitors.

fn volatile_level(&self) -> VolatileLevel

Volatile granularity. Default Always for backwards compatibility.

fn workbook_seed(&self) -> u64

A stable workbook seed for RNG composition.

fn recalc_epoch(&self) -> u64

Recalc epoch that increments on each full recalc when appropriate.

fn workbook_sheet_count(&self) -> Option<usize>

Number of active sheets in the workbook, if known.

fn sheet_index_by_name(&self, sheet: &str) -> Option<usize>

Excel-style 1-based active-sheet index for a sheet name, if known.

fn current_sheet_index(&self, current_sheet: &str) -> Option<usize>

Excel-style 1-based active-sheet index for the current formula sheet, if known.

fn inspect_reference( &self, reference: &ReferenceType, current_sheet: &str, ) -> Result<Option<ReferenceInfo>, ExcelError>

Inspect reference metadata without materializing referenced values.

fn formula_text_at_cell( &self, cell: CellRef, ) -> Result<Option<String>, ExcelError>

Retrieve formula text for a concrete cell, if that cell stores a formula.

fn used_rows_for_columns( &self, sheet: &str, start_col: u32, end_col: u32, ) -> Option<(u32, u32)>

Optional: Return the min/max used rows for a set of columns on a sheet. When None, the backend does not provide used-region hints.

fn used_cols_for_rows( &self, sheet: &str, start_row: u32, end_row: u32, ) -> Option<(u32, u32)>

Optional: Return the min/max used columns for a set of rows on a sheet. When None, the backend does not provide used-region hints.

fn sheet_bounds(&self, sheet: &str) -> Option<(u32, u32)>

Optional: Physical sheet bounds (max rows, max cols) if known.

fn data_snapshot_id(&self) -> u64

Monotonic identifier for the current data snapshot; increments on mutation.

fn backend_caps(&self) -> BackendCaps

Backend capability advertisement for IO/adapters.

fn build_lookup_index( &self, view: &RangeView<'_>, axis: LookupAxis, ) -> Option<Arc<LookupIndex>>

Optional: Build or fetch an exact-match lookup index over an Arrow-backed view. Implementations should return None if not supported or unsafe.

fn date_system(&self) -> DateSystem

Workbook date system selection (1900 vs 1904). Defaults to 1900 for compatibility.

fn resolve_cell_reference_value( &self, sheet: Option<&str>, row: u32, col: u32, current_sheet: &str, ) -> Result<LiteralValue, ExcelError>

Resolve a single-cell reference as a scalar value.

fn build_criteria_mask( &self, view: &RangeView<'_>, col_in_view: usize, pred: &CriteriaPredicate, ) -> Option<Arc<BooleanArray>>

Optional: Build or fetch a cached boolean mask for a criterion over an Arrow-backed view. Implementations should return None if not supported.

fn build_row_visibility_mask( &self, view: &RangeView<'_>, mode: VisibilityMaskMode, ) -> Option<Arc<BooleanArray>>

Optional: Build row-visibility mask aligned to view rows. Returns None if not supported by the underlying context.

fn locale(&self) -> Locale

Locale provider: invariant by default

fn timezone(&self) -> &TimeZoneSpec

Timezone spec for date/time functions.

impl<R> FunctionProvider for Engine<R>

where R: EvaluationContext,

fn get_function(&self, prefix: &str, name: &str) -> Option<Arc<dyn Function>>

impl<R> NamedRangeResolver for Engine<R>

where R: EvaluationContext,

fn resolve_named_range_reference( &self, name: &str, ) -> Result<Vec<Vec<LiteralValue>>, ExcelError>

impl<R> RangeResolver for Engine<R>

where R: EvaluationContext,

fn resolve_range_reference( &self, sheet: Option<&str>, sr: Option<u32>, sc: Option<u32>, er: Option<u32>, ec: Option<u32>, ) -> Result<Box<dyn Range>, ExcelError>

impl<R> ReferenceResolver for Engine<R>

where R: EvaluationContext,

fn resolve_cell_reference( &self, sheet: Option<&str>, row: u32, col: u32, ) -> Result<LiteralValue, ExcelError>

impl<R> Resolver for Engine<R>

where R: EvaluationContext,

fn resolve_range_like( &self, r: &ReferenceType, ) -> Result<Box<dyn Range>, ExcelError>

impl<R> SourceResolver for Engine<R>

where R: EvaluationContext,

fn source_scalar_version(&self, name: &str) -> Option<u64>

fn resolve_source_scalar(&self, name: &str) -> Result<LiteralValue, ExcelError>

fn source_table_version(&self, name: &str) -> Option<u64>

fn resolve_source_table(&self, name: &str) -> Result<Box<dyn Table>, ExcelError>

impl<R> TableResolver for Engine<R>

where R: EvaluationContext,

fn resolve_table_reference( &self, tref: &TableReference, ) -> Result<Box<dyn Table>, ExcelError>