Execution Engine

src/execution/ drives PhysicalPlan trees using the Volcano (iterator) model. Every operator pulls tuples from its children, coordinating closely with transactions, storage, and expression evaluation.

Core Components

Execution Flow

1. ExecutionEngine::execute calls init on the root plan (and recursively on children).
2. The engine loops calling next, with parents pulling tuples from children.
3. ExecutionContext supplies transaction snapshots, lock helpers, and expression evaluation per call.
4. Once next returns None, the accumulated results are returned to the caller (CLI, HTTP API, or tests).

Operator Examples

• PhysicalSeqScan – acquires a table_stream from the storage engine, uses ScanPrefetch for batching, and relies on TxnContext::read_visible_tuple for MVCC.
• PhysicalIndexScan – uses index_stream, tracks invisible_hits, and notifies the catalog when garbage accumulates.
• PhysicalUpdate/PhysicalDelete – call prepare_row_for_write to re-validate locks and the latest tuple before invoking apply_update/delete.
• PhysicalNestedLoopJoin – showcases the parent/child pull loop and acts as a baseline for more advanced joins.

Interactions

• StorageEngine – all data access goes through handles/streams, keeping execution storage-agnostic.
• Transaction – TxnContext enforces locking, snapshots, and undo logging; operators never talk to LockManager directly.
• Expression – ExecutionContext::eval_expr / eval_predicate evaluate expressions built by the planner.
• Optimizer/Planner – execution honours the plan as-is; all structural choices happen upstream.

Teaching Ideas

• Implement a new operator (e.g., PhysicalMergeJoin) to see how ExecutionContext support generalises.
• Add adaptive prefetching inside PhysicalSeqScan to explore iterator hints.
• Enable RUST_LOG=execution=trace to watch the init/next call sequence during a query.

Further reading: The Volcano Execution Model