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

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)

pub fn last_virtual_dep_telemetry(&self) -> &VirtualDepTelemetry

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 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 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 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

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 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 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 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 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 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.

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<'_>

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 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 date_system(&self) -> DateSystem

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

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 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>