From 3db0c3212ef3d4a459b7222f73770c139bec936b Mon Sep 17 00:00:00 2001 From: cjkenn Date: Fri, 20 Nov 2020 12:09:37 -0500 Subject: [PATCH 1/2] add mir-opt section for optimization fuel --- src/mir/optimizations.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/src/mir/optimizations.md b/src/mir/optimizations.md index 65323ed52..b34520f35 100644 --- a/src/mir/optimizations.md +++ b/src/mir/optimizations.md @@ -60,3 +60,24 @@ want to query whether your optimization pass should run, you can check the current level using `tcx.sess.opts.debugging_opts.mir_opt_level`. [compiler MCP]: https://github.com/rust-lang/compiler-team/issues/319 + +## Optimization fuel + +Optimization fuel is a compiler option (`-Z fuel==`) that allows for fine grained +control over which optimizations can be applied during compilation: each optimization reduces +fuel by 1, and when fuel reaches 0 no more optimizations are applied. This can help with debugging +and identifying problems with optimizations. + +MIR optimizations respect fuel, and in general each pass should check fuel by calling +[`tcx.consider_optimizing`][consideroptimizing] and skipping the optimization if fuel +is empty. There are a few considerations: + +1. If the pass is considered "guaranteed" (for example, it should always be run because it is +needed for correctness), then fuel should not be used. An example of this is `PromoteTemps`. +2. In some cases, an initial pass is performed to gather candidates, which are then iterated to +perform optimizations. In these situations, we should allow for the initial gathering pass +and then check fuel as close to the mutation as possible. This allows for the best +debugging experience, because we can determine where in the list of candidates an optimization +may have been misapplied. Examples of this are `InstCombine` and `ConstantPropagation`. + +[consideroptimizing]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.consider_optimizing From 4976829b9556370146738e1b1b3f1d94f4df50d3 Mon Sep 17 00:00:00 2001 From: cjkenn Date: Fri, 20 Nov 2020 14:51:29 -0500 Subject: [PATCH 2/2] add small explanation of why fuel can be useful for debugging --- src/mir/optimizations.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/mir/optimizations.md b/src/mir/optimizations.md index b34520f35..080c8fd3f 100644 --- a/src/mir/optimizations.md +++ b/src/mir/optimizations.md @@ -65,8 +65,10 @@ current level using `tcx.sess.opts.debugging_opts.mir_opt_level`. Optimization fuel is a compiler option (`-Z fuel==`) that allows for fine grained control over which optimizations can be applied during compilation: each optimization reduces -fuel by 1, and when fuel reaches 0 no more optimizations are applied. This can help with debugging -and identifying problems with optimizations. +fuel by 1, and when fuel reaches 0 no more optimizations are applied. The primary use of fuel +is debugging optimizations that may be incorrect or misapplied. By changing the fuel +value, you can bisect a compilation session down to the exact incorrect optimization +(this behaves like a kind of binary search through the optimizations). MIR optimizations respect fuel, and in general each pass should check fuel by calling [`tcx.consider_optimizing`][consideroptimizing] and skipping the optimization if fuel