Generalize interpreter traversal over CFG, Block, DiGraph, and UnGraph bodies by zhenrongliew · Pull Request #684 · QuEraComputing/kirin

zhenrongliew · 2026-07-15T19:21:47Z

Generalize interpreter body traversal beyond CFGs

Part of #667. This addresses the second follow-up identified in the issue:

Investigate why the interpreter framework is specialized to Region/CFG. It should support bodies such as Block, DiGraph, and UnGraph, demonstrated with a language combining computational graphs and regular SSA IR.

Depends on the Region → CFG rename PR.

Summary

Introduces a closed Body vocabulary covering:
- Cfg
- Block
- DiGraph
- UnGraph
Allows callable statements to own CFG, Block, DiGraph, or UnGraph bodies.
Separates body representation traversal from invocation context:
- CfgFrame traverses CFGs.
- BlockFrame traverses one Block.
- DiGraphFrame traverses a directed computational graph.
- CallFrame manages callee resolution, activation lifetime, returns, and caller result binding.
Adds a default topological DiGraph walker and reports an error for directed cycles.
Provides no universal UnGraph walker. A compiler supplies UnGraph scheduling policy through FrameBuild::from_ungraph_entry; otherwise the interpreter reports NoDefaultWalker.
Adds a mixed test language combining ordinary CFG SSA, callable Blocks, directed computational graphs, structured Blocks, and callable UnGraph policy.

Scope

Body remains an intentionally closed enum of Kirin’s built-in body representations. The extensibility point for UnGraph is its traversal policy, since an undirected graph has no inherent execution order.

The remaining toy-lang sparse/dense liveness simplification from #667 is left for a separate PR.

This commit introduces a new test file `body_kinds.rs` that contains acceptance tests for the generic interpreter bodies. The tests cover various scenarios including: - A Cfg-bodied `main` calling a DiGraph-bodied function. - A statement inside a Cfg block that owns a DiGraph body. - A linear callable with a flat instruction list. - Ensuring that graph nodes run in topological order. These tests aim to validate the interaction between Cfg-SSA code and DiGraph computational graphs, ensuring correct execution and error handling.

- Renamed `BodyFrame` to `BlockFrame` and adjusted related documentation to reflect the new terminology. - Enhanced the `ToyFrame` enum to include `BlockFrame` and `CfgFrame`, replacing `BodyFrame`. - Updated `FrameBuild` implementations in `ToyFrame` and `TracingFrame` to accommodate the new frame types. - Revised tests in `tests/body_kinds.rs` to ensure compatibility with the updated frame structure. - Added comprehensive tests for structured control flow (SCF) operations, including `scf.if` and `scf.for`, demonstrating their integration with the new frame types. - Implemented a custom callable-UnGraph policy to handle ungraph traversal, ensuring proper execution order and output handling.

Resolve conflicts from the Region->CFG rename (#683, now in rust): - Apply the same Cfg->CFG / CFGs->CFG naming to this branch's changes. - Keep this branch's restructure of concrete/frames.rs into concrete/frames/ (drop the stale single-file frames.rs that rust only renamed). - Drop now-unused CFG imports surfaced by the merge. All tests (1234) and doctests pass; fmt and clippy clean.

Builders set `SSAInfo.kind` (use→def) but nobody ever populated `SSAInfo.uses` (def→use). Both finalize paths just copied an always-empty vec through. So finalized IR shipped an empty def-use. - `StageInfo::rebuild_use_index()`: clears every live value's `uses,` then scans each live statement's operands (`HasArguments` order) and records one `Use { stmt, operand_index } `on the value each slot reads. Idempotent, so the future rewriter can re-run it. Skips deleted statements/tombstoned SSAs. - both `finalize()` and `finalize_unchecked()` call it before returning. - `Use` gains `new()` + `stmt()/operand_index()` accessors, `Copy`, and serde parity with its container `SSAInfo`. - `rebuild_use_index` now scan over nodes.digraphs, pushing a `DiGraphYield { graph, index }` into `SSAInfo.uses`. ```rust pub enum Use { StatementOperand { stmt: Statement, index: usize }, DiGraphYield { graph: DiGraph, index: usize }, } ```

…_state_mut methods for state management. - Introduced the DenseBackwardState trait to handle state renaming and forgetting. - Updated the LiveSet implementation to conform to the DenseBackwardState contract. - Modified various interpreters and frames to utilize the new DenseBackwardState trait. - Enhanced documentation to clarify the role of DenseBackwardState in the context of classic liveness and dense backward analysis. - Added tests to validate the behavior of the new forward dataflow engine with constant propagation.

… traversal - Added AbstractDiGraphFrame to handle graph bodies in a single pass. - Updated Owner enum to include Graph variant for executable graph bodies. - Enhanced SparseForwardInterpreter to support DiGraph bodies. - Modified tests to validate the new graph handling and ensure correct execution order.

Roger-luo

just need to address the leftover comments

- Added a test to validate the mismatch between callable-body policies when the `#[interpret(body_frames = ...)]` attribute is not specified

…ts split by consumer.

- Introduced `BlockParent` enum to represent the immediate owner of a block, allowing for clearer ownership semantics between CFGs and statements. - Updated `BlockInfo` to include a `predecessors` field for reverse control-flow indexing, facilitating demand analysis. - Modified builders to correctly assign parents to blocks and graphs, ensuring ownership integrity during construction. - Removed unused boundary location structures and related code to streamline the anchor module.

…point fact retrieval

…ry efficiency

…tStatement + PreviousStatement

…dual parameters

zhenrongliew added 4 commits July 9, 2026 17:45

refactor: rename regions to cfgs and update related tests

f800609

Refactor terminology from Region to Cfg across the codebase

aed4c23

zhenrongliew requested a review from Roger-luo July 15, 2026 19:22

zhenrongliew added area: interpreter Area: issues related to the interpreter. area: Rust Area: issues and pull requests related to Rust code. area: Kirin-rs Area: Rust-version Kirin related components. labels Jul 15, 2026

Base automatically changed from dl/rename-region-to-cfg to rust July 17, 2026 04:11

Roger-luo reviewed Jul 17, 2026

View reviewed changes

Comment thread crates/kirin-interpreter/src/core/query.rs

zhenrongliew and others added 2 commits July 22, 2026 11:22

refactor: simplify liveness analysis by removing demand pre-pass

969914e