Struct Engine 

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

Fields

graph: DependencyGraph

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 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 sheet_id(&self, name: &str) -> Option<SheetId>

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 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 set_cell_value( &mut self, sheet: &str, row: u32, col: u32, value: LiteralValue, ) -> Result<(), ExcelError>

Set a cell value

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>

Evaluate a single vertex. This is the core of the sequential evaluation logic for Milestone 3.1.

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

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

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

Evaluate all dirty/volatile vertices

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 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: &AtomicBool, ) -> Result<EvalResult, ExcelError>

Evaluate all dirty/volatile vertices with cancellation support

pub fn evaluate_until_cancellable( &mut self, targets: &[&str], cancel_flag: &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: 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 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<&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 arrow_fastpath_enabled(&self) -> bool

Feature gate: enable Arrow fast paths in builtins (e.g., SUMIFS). Default is false; engines that wish to enable must override.

fn date_system(&self) -> DateSystem

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

fn build_criteria_mask( &self, view: &ArrowRangeView<'_>, 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 provider for date/time functions Default: Local (Excel-compatible behavior) Functions should use local timezone when this returns Local

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> TableResolver for Engine<R>

where R: EvaluationContext,

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