Document and improve MIR transform passes

[DevaanshPathak]

This commit enhances documentation and fixes several issues in the MIR transform optimization passes (compiler/rustc_mir_transform).

Documentation improvements

ConstParamHasTy interaction (#127030)

• Extensively documented the drop shim builder param-env issue that affects types with const parameters
• Added detailed explanation of root cause: build_drop_shim uses drop_in_place intrinsic's DefId instead of dropped type's DefId, causing param-env to lack ConstArgHasType predicates
• Documented workaround in inline.rs (preventing drop glue inlining for types with const params until monomorphization)
• Added corresponding documentation in shim.rs at the problematic typing_env construction site
• Outlined three potential fix approaches with implementation details

Destination propagation (dest_prop.rs)

• Documented storage statement handling: clarified why storage statements are currently deleted and provided TODO with specific implementation steps for merging storage ranges instead
• Enhanced subtyping check documentation: explained soundness requirements for exact type equality and referenced issue change handling of subtyping to be less fragile after analysis #112651

Global Value Numbering (gvn.rs)

• Dramatically improved pointer identity issue documentation (issue Anonymous allocations in statics get duplicated for multiple codegen units #79738) at 4 locations, explaining:
  • CTFE address aliasing problems
  • Pointer provenance loss during const prop
  • Interior pointer identity issues
  • Safety net assertions
• Enhanced codegen uniformity documentation: explained why only GlobalAlloc::Memory works in Indirect constants and provided 3-step improvement plan for future work

Dataflow constant propagation (dataflow_const_prop.rs)

• Clarified tail call termination behavior: documented that tail calls naturally terminate dataflow analysis, which is correct

Inlining (inline.rs)

• Documented tail call constraints in two locations: explained why tail calls aren't inlined (complex transformations required, may defeat performance purpose)
• Added note explaining why single-caller detection isn't implemented (requires inter-procedural analysis not currently available)

Code improvements

GVN subtype handling fix

• Fixed subtype checking to use relate_types with Variance::Covariant
• Now correctly handles assignments with valid subtyping relationships, including Subtype casts inserted by add_subtyping_projections pass
• Uses same logic as MIR validator for consistency

Inline heuristics enhancement

• Added 50% bonus threshold for single-block functions (likely trivial getters/setters)
• Improves inlining decisions for very small, high-value functions

New files

compiler/rustc_mir_transform/README.md

Created comprehensive developer guide covering:

• Key optimization passes (dest_prop, GVN, dataflow const prop, inlining)
• How to add new passes
• Testing commands
• Pass ordering considerations
• Known limitations (ConstParamHasTy issue)
• Common patterns and performance considerations

All changes maintain backward compatibility and follow existing conventions. No functional changes to optimization behavior except for the GVN subtype fix, which enables optimizations that were previously incorrectly rejected.

[rustbot]

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

[rustbot]

r? @lcnr

rustbot has assigned @lcnr.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

⚠️ Warning ⚠️

• There are issue links (such as #123) in the commit messages of the following commits.
  Please move them to the PR description, to avoid spamming the issues with references to the commit, and so this bot can automatically canonicalize them to avoid issues with subtree.
  • 970004c

[rust-log-analyzer]

The job tidy failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

- // other allocation kinds (like GlobalAlloc::Static, GlobalAlloc::Function, + // other allocation kinds (like GlobalAlloc::Static, GlobalAlloc::Function, // GlobalAlloc::VTable) require different handling in codegen. // // TODO: Ideally codegen should handle all GlobalAlloc kinds uniformly in Diff in /checkout/compiler/rustc_mir_transform/src/gvn.rs:1940: { let local_ty = self.local_decls[local].ty; let rvalue_ty = rvalue.ty(self.local_decls, self.tcx); - + // Check if the assignment is valid. We accept both exact type equality // and valid subtyping relationships (handled by Subtype casts inserted // by the `add_subtyping_projections` pass). The type checker uses Diff in /checkout/compiler/rustc_mir_transform/src/gvn.rs:1954: // as the validator. This allows GVN to work correctly with // Subtype casts that may be present. use rustc_middle::ty::Variance; - crate::util::relate_types(self.tcx, self.typing_env(), Variance::Covariant, rvalue_ty, local_ty) + crate::util::relate_types( + self.tcx, + self.typing_env(), + Variance::Covariant, + rvalue_ty, + local_ty, + ) }; - + if types_compatible { let value = value.unwrap_or_else(|| self.new_opaque(rvalue_ty)); self.assign(local, value); Diff in /checkout/compiler/rustc_mir_transform/src/inline.rs:388: if callee_body.basic_blocks.len() <= 3 { threshold += threshold / 4; } - + // Give an extra bonus to very tiny functions (single block, likely trivial getters/setters) // These are especially profitable to inline as they often disappear entirely after optimization if callee_body.basic_blocks.len() == 1 { Diff in /checkout/compiler/rustc_mir_transform/src/inline.rs:395: threshold += threshold / 2; } - + debug!(" final inline threshold = {}", threshold);