Crate rucc_opt 

The pass manager, the acyclic e-graph, the rewrite rules and the analyses.

Design: spec/09-optimizer.md. Layer rank 9, see spec/18-package-layout.md.

What is here

The pass manager and four passes. pipeline holds the six pipelines, one per optimization level, written out rather than assembled from flags, along with the fuel, the dumps and the verification that section 9.10 asks of every pass. fold is the first pass through it, simplify is the peephole the e-graph will eventually absorb, narrow takes the width back off arithmetic that C promoted, and dce is what clears up after all three of them. uses is the one thing two of them share, which is a count of who reads what.

stats is what a pass has to return, and optinfo is that printed. A pass reports what it did and what it gave up on, and there is no other way for it to tell the manager it changed anything, so the instrumentation cannot be the thing nobody got round to. Section 42.2 of spec/optimizer/42-measurement.md counted what happens otherwise.

cfg, dom and loops are the analyses so far, and everything in spec/optimizer/07 through spec/optimizer/11 is built on them. cfg is the shape of a function with the instructions taken out, dom answers what every path has to go through, forwards and backwards, and loops says what loops there are, how they nest, and which cycles are not loops at all.

The e-graph and the rewrite rule set are still M4 work and are not here yet. So is the analysis manager, which section 9.10 also asks for: a pass declares which analyses it requires, preserves and invalidates, and a debug check recomputes one it claimed to preserve and compares. The three here are built by their callers for now, and the manager lands with the passes that consume more than one of them at a time.

Stability

Every crate in the workspace is published, and publishing implies a promise. This one is tier 3: its Rust API is explicitly unstable and will change without a major version bump. Depend on the rucc binary’s behaviour, not on this.

Re-exports

pub use cfg::Cfg;

pub use dom::Dominators;

pub use dom::PostDominators;

pub use fuel::Fuel;

pub use loops::Exit;

pub use loops::LoopId;

pub use loops::Loops;

pub use optinfo::Wants;

pub use pass::PASSES;

pub use pass::Pass;

pub use pipeline::Dump;

pub use pipeline::Dumps;

pub use pipeline::Options;

pub use pipeline::Remark;

pub use pipeline::Report;

pub use pipeline::run;

pub use stats::Stats;

Modules

cfg

The control flow graph, which is the shape of a function with the instructions taken out.

dce

Dead code elimination: an instruction nothing uses and nothing depends on goes away.

dom

Dominance, which is the question of what every path has to go through.

fold

Constant folding: an instruction whose operands are all constants becomes a constant.

fuel

How many transformations a pass is allowed before it stops transforming.

loops

The loop forest: what loops there are, how they nest, and what is in a cycle that is not one.

narrow

Width narrowing: arithmetic redone at the width the program actually uses.

optinfo

-fopt-info, which is the compiler saying what it did and what it nearly did.

pass

What a pass is, and the list of the ones this compiler has.

pipeline

The pipelines, one per optimization level, and the manager that runs one.

simplify

Peephole rewrites: a small pattern of instructions becomes a smaller one.

stats

What a pass has to say about what it did, and about what it wanted to do and could not.

uses

Who reads what, counted by occurrence.

Constants

MILESTONE

The milestone in spec/17-milestones.md that fills this crate in.