From fd79ed42254d7483569ccc48ef35a79635ed5881 Mon Sep 17 00:00:00 2001 From: Camelid Date: Mon, 14 Sep 2020 20:05:00 -0700 Subject: [PATCH 1/5] Add docs for `BasicBlock` --- compiler/rustc_middle/src/mir/mod.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/compiler/rustc_middle/src/mir/mod.rs b/compiler/rustc_middle/src/mir/mod.rs index d32a7a4062e27..aeaea0d102c0d 100644 --- a/compiler/rustc_middle/src/mir/mod.rs +++ b/compiler/rustc_middle/src/mir/mod.rs @@ -1076,6 +1076,19 @@ pub struct VarDebugInfo<'tcx> { // BasicBlock rustc_index::newtype_index! { + /// The unit of the MIR [control-flow graph][CFG]. + /// + /// There is no branching (e.g., `if`s, function calls, etc.) within a basic block, which makes + /// it easier to do [data-flow analyses] and optimizations. Basic blocks consist of a series of + /// [statements][`Statement`], ending with a [terminator][`Terminator`]. Basic blocks can have + /// multiple predecessors and successors. + /// + /// Read more about basic blocks in the [rustc-dev-guide][guide-mir]. + /// + /// [CFG]: https://rustc-dev-guide.rust-lang.org/appendix/background.html#cfg + /// [data-flow analyses]: + /// https://rustc-dev-guide.rust-lang.org/appendix/background.html#what-is-a-dataflow-analysis + /// [guide-mir]: https://rustc-dev-guide.rust-lang.org/mir/ pub struct BasicBlock { derive [HashStable] DEBUG_FORMAT = "bb{}", @@ -1092,6 +1105,7 @@ impl BasicBlock { /////////////////////////////////////////////////////////////////////////// // BasicBlockData and Terminator +/// See [`BasicBlock`] for documentation on what basic blocks are at a high level. #[derive(Clone, Debug, TyEncodable, TyDecodable, HashStable, TypeFoldable)] pub struct BasicBlockData<'tcx> { /// List of statements in this block. From a872ec47145ce3a82c39bedaca21b99e867d9be2 Mon Sep 17 00:00:00 2001 From: Camelid Date: Mon, 14 Sep 2020 20:10:29 -0700 Subject: [PATCH 2/5] Clarify how branching works in a CFG --- compiler/rustc_middle/src/mir/mod.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/compiler/rustc_middle/src/mir/mod.rs b/compiler/rustc_middle/src/mir/mod.rs index aeaea0d102c0d..6f6585d383d52 100644 --- a/compiler/rustc_middle/src/mir/mod.rs +++ b/compiler/rustc_middle/src/mir/mod.rs @@ -1079,9 +1079,11 @@ rustc_index::newtype_index! { /// The unit of the MIR [control-flow graph][CFG]. /// /// There is no branching (e.g., `if`s, function calls, etc.) within a basic block, which makes - /// it easier to do [data-flow analyses] and optimizations. Basic blocks consist of a series of - /// [statements][`Statement`], ending with a [terminator][`Terminator`]. Basic blocks can have - /// multiple predecessors and successors. + /// it easier to do [data-flow analyses] and optimizations. Instead, branches are represented + /// as an edge in a graph between basic blocks. + /// + /// Basic blocks consist of a series of [statements][`Statement`], ending with a + /// [terminator][`Terminator`]. Basic blocks can have multiple predecessors and successors. /// /// Read more about basic blocks in the [rustc-dev-guide][guide-mir]. /// From c051f61d3c078343db70e355feea808892deed75 Mon Sep 17 00:00:00 2001 From: Camelid <37223377+camelid@users.noreply.github.com> Date: Tue, 15 Sep 2020 09:50:55 -0700 Subject: [PATCH 3/5] Improve wording Co-authored-by: Joshua Nelson --- compiler/rustc_middle/src/mir/mod.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/compiler/rustc_middle/src/mir/mod.rs b/compiler/rustc_middle/src/mir/mod.rs index 6f6585d383d52..e6bb746f618fb 100644 --- a/compiler/rustc_middle/src/mir/mod.rs +++ b/compiler/rustc_middle/src/mir/mod.rs @@ -1078,12 +1078,12 @@ pub struct VarDebugInfo<'tcx> { rustc_index::newtype_index! { /// The unit of the MIR [control-flow graph][CFG]. /// - /// There is no branching (e.g., `if`s, function calls, etc.) within a basic block, which makes + /// There are no branches (e.g., `if`s, function calls, etc.) within a basic block, which makes /// it easier to do [data-flow analyses] and optimizations. Instead, branches are represented /// as an edge in a graph between basic blocks. /// - /// Basic blocks consist of a series of [statements][`Statement`], ending with a - /// [terminator][`Terminator`]. Basic blocks can have multiple predecessors and successors. + /// Basic blocks consist of a series of [statements][Statement], ending with a + /// [terminator][Terminator]. Basic blocks can have multiple predecessors and successors. /// /// Read more about basic blocks in the [rustc-dev-guide][guide-mir]. /// From 57eb29cd2dc30c47b613ced135422a4120bc6a78 Mon Sep 17 00:00:00 2001 From: Camelid Date: Wed, 16 Sep 2020 15:31:56 -0700 Subject: [PATCH 4/5] Update based on review suggestions --- compiler/rustc_middle/src/mir/mod.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/compiler/rustc_middle/src/mir/mod.rs b/compiler/rustc_middle/src/mir/mod.rs index e6bb746f618fb..58b69d022d985 100644 --- a/compiler/rustc_middle/src/mir/mod.rs +++ b/compiler/rustc_middle/src/mir/mod.rs @@ -1076,20 +1076,24 @@ pub struct VarDebugInfo<'tcx> { // BasicBlock rustc_index::newtype_index! { - /// The unit of the MIR [control-flow graph][CFG]. + /// A node in the MIR [control-flow graph][CFG]. /// /// There are no branches (e.g., `if`s, function calls, etc.) within a basic block, which makes /// it easier to do [data-flow analyses] and optimizations. Instead, branches are represented /// as an edge in a graph between basic blocks. /// /// Basic blocks consist of a series of [statements][Statement], ending with a - /// [terminator][Terminator]. Basic blocks can have multiple predecessors and successors. + /// [terminator][Terminator]. Basic blocks can have multiple predecessors and successors, + /// however there is a MIR pass ([`CriticalCallEdges`]) that removes *critical edges*, which + /// are edges that go from a multi-successor node to a multi-predecessor node. This pass is + /// needed because some analyses require that there are no critical edges in the CFG. /// /// Read more about basic blocks in the [rustc-dev-guide][guide-mir]. /// /// [CFG]: https://rustc-dev-guide.rust-lang.org/appendix/background.html#cfg /// [data-flow analyses]: /// https://rustc-dev-guide.rust-lang.org/appendix/background.html#what-is-a-dataflow-analysis + /// [`CriticalCallEdges`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/transform/add_call_guards/enum.AddCallGuards.html#variant.CriticalCallEdges /// [guide-mir]: https://rustc-dev-guide.rust-lang.org/mir/ pub struct BasicBlock { derive [HashStable] From 451f7f6b125111588feb19d2e9675aa995a2e53f Mon Sep 17 00:00:00 2001 From: Camelid Date: Thu, 17 Sep 2020 11:38:40 -0700 Subject: [PATCH 5/5] Use relative link instead of absolute --- compiler/rustc_middle/src/mir/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compiler/rustc_middle/src/mir/mod.rs b/compiler/rustc_middle/src/mir/mod.rs index 58b69d022d985..ac2c273f74b0c 100644 --- a/compiler/rustc_middle/src/mir/mod.rs +++ b/compiler/rustc_middle/src/mir/mod.rs @@ -1093,7 +1093,7 @@ rustc_index::newtype_index! { /// [CFG]: https://rustc-dev-guide.rust-lang.org/appendix/background.html#cfg /// [data-flow analyses]: /// https://rustc-dev-guide.rust-lang.org/appendix/background.html#what-is-a-dataflow-analysis - /// [`CriticalCallEdges`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/transform/add_call_guards/enum.AddCallGuards.html#variant.CriticalCallEdges + /// [`CriticalCallEdges`]: ../../rustc_mir/transform/add_call_guards/enum.AddCallGuards.html#variant.CriticalCallEdges /// [guide-mir]: https://rustc-dev-guide.rust-lang.org/mir/ pub struct BasicBlock { derive [HashStable]