From 584f9205f1f1c31a714c016f364aed758bd1f6a9 Mon Sep 17 00:00:00 2001 From: Camelid Date: Tue, 10 Nov 2020 16:44:16 -0800 Subject: [PATCH 1/7] Add a section on identifiers in the MIR --- src/identifiers.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/src/identifiers.md b/src/identifiers.md index f485132c6..7c20792ae 100644 --- a/src/identifiers.md +++ b/src/identifiers.md @@ -60,4 +60,27 @@ See the [HIR chapter][hir-map] for more detailed information. ## In the MIR -**TODO** +- [`BasicBlock`] identifies a *basic block*. It points to an instance of + [`BasicBlockData`]. +- [`Local`] identifies a local variable in a function. Its associated data is in + [`LocalDecl`]. +- [`Field`] identifies a struct's, union's, or enum variant's field. It is used + as a "projection" in [`Place`]. +- [`SourceScope`] identifies a name scope in the original source code. +- [`Promoted`] identifies a promoted constant (related to const evaluation). +- [`GlobalId`] identifies a global variable: a `const`, a `static`, a certain + kind of `const fn`, or a promoted constant. +- [`Location`] represents the location in the MIR of a statement or terminator. + It identifies the block (using [`BasicBlock`]) and the index of the statement + or terminator in the block. + +[`BasicBlock`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.BasicBlock.html +[`BasicBlockData`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.BasicBlockData.html +[`Local`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Local.html +[`LocalDecl`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.LocalDecl.html +[`Field`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Field.html +[`Place`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Place.html +[`SourceScope`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.SourceScope.html +[`Promoted`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Promoted.html +[`GlobalId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.GlobalId.html +[`Location`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Location.html From cd29a132bcb28d0001693e05026a79b383dad0bd Mon Sep 17 00:00:00 2001 From: Camelid Date: Tue, 10 Nov 2020 17:24:47 -0800 Subject: [PATCH 2/7] Better wording --- src/identifiers.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/identifiers.md b/src/identifiers.md index 7c20792ae..45e700d5b 100644 --- a/src/identifiers.md +++ b/src/identifiers.md @@ -68,8 +68,8 @@ See the [HIR chapter][hir-map] for more detailed information. as a "projection" in [`Place`]. - [`SourceScope`] identifies a name scope in the original source code. - [`Promoted`] identifies a promoted constant (related to const evaluation). -- [`GlobalId`] identifies a global variable: a `const`, a `static`, a certain - kind of `const fn`, or a promoted constant. +- [`GlobalId`] identifies a global variable: a `const`, a `static`, a `const fn` + where all arguments are [zero-sized types], or a promoted constant. - [`Location`] represents the location in the MIR of a statement or terminator. It identifies the block (using [`BasicBlock`]) and the index of the statement or terminator in the block. @@ -84,3 +84,4 @@ See the [HIR chapter][hir-map] for more detailed information. [`Promoted`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Promoted.html [`GlobalId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.GlobalId.html [`Location`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Location.html +[zero-sized types]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts From 4d7952f02adb4133f29ab4e24ba9a6e78c42b5f3 Mon Sep 17 00:00:00 2001 From: Camelid Date: Tue, 10 Nov 2020 17:32:50 -0800 Subject: [PATCH 3/7] Use loose lists; fix typo; fix link --- src/identifiers.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/identifiers.md b/src/identifiers.md index 45e700d5b..fd105421f 100644 --- a/src/identifiers.md +++ b/src/identifiers.md @@ -12,7 +12,7 @@ A [`NodeId`] is an identifier number that uniquely identifies an AST node within a crate. Every node in the AST has its own [`NodeId`], including top-level items such as structs, but also individual statements and expressions. -However, because they are absolute within in a crate, adding or removing a single +However, because they are absolute within a crate, adding or removing a single node in the AST causes all the subsequent [`NodeId`]s to change. This renders [`NodeId`]s pretty much useless for incremental compilation, where you want as few things as possible to change. @@ -31,14 +31,17 @@ The HIR uses a bunch of different identifiers that coexist and serve different p the crate the definition comes from, and a [`DefIndex`] which identifies the definition within the crate. Unlike [`NodeId`]s, there isn't a [`DefId`] for every expression, which makes them more stable across compilations. + - A [`LocalDefId`] is basically a [`DefId`] that is known to come from the current crate. This allows us to drop the [`CrateNum`] part, and use the type system to ensure that only local definitions are passed to functions that expect a local definition. + - A [`HirId`] uniquely identifies a node in the HIR of the current crate. It is composed of two parts: an `owner` and a `local_id` that is unique within the `owner`. This combination makes for more stable values which are helpful for incremental compilation. Unlike [`DefId`]s, a [`HirId`] can refer to [fine-grained entities][Node] like expressions, but stays local to the current crate. + - A [`BodyId`] identifies a HIR [`Body`] in the current crate. It is currenty only a wrapper around a [`HirId`]. For more info about HIR bodies, please refer to the [HIR chapter][hir-bodies]. @@ -62,14 +65,20 @@ See the [HIR chapter][hir-map] for more detailed information. - [`BasicBlock`] identifies a *basic block*. It points to an instance of [`BasicBlockData`]. + - [`Local`] identifies a local variable in a function. Its associated data is in [`LocalDecl`]. + - [`Field`] identifies a struct's, union's, or enum variant's field. It is used as a "projection" in [`Place`]. + - [`SourceScope`] identifies a name scope in the original source code. + - [`Promoted`] identifies a promoted constant (related to const evaluation). + - [`GlobalId`] identifies a global variable: a `const`, a `static`, a `const fn` where all arguments are [zero-sized types], or a promoted constant. + - [`Location`] represents the location in the MIR of a statement or terminator. It identifies the block (using [`BasicBlock`]) and the index of the statement or terminator in the block. @@ -82,6 +91,6 @@ See the [HIR chapter][hir-map] for more detailed information. [`Place`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Place.html [`SourceScope`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.SourceScope.html [`Promoted`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Promoted.html -[`GlobalId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.GlobalId.html +[`GlobalId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/struct.GlobalId.html [`Location`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Location.html [zero-sized types]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts From cb110c2fc419792e411a60d6cd98a124d5483917 Mon Sep 17 00:00:00 2001 From: Camelid Date: Thu, 12 Nov 2020 15:16:15 -0800 Subject: [PATCH 4/7] Update info --- src/identifiers.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/identifiers.md b/src/identifiers.md index fd105421f..9e89d21c3 100644 --- a/src/identifiers.md +++ b/src/identifiers.md @@ -72,9 +72,12 @@ See the [HIR chapter][hir-map] for more detailed information. - [`Field`] identifies a struct's, union's, or enum variant's field. It is used as a "projection" in [`Place`]. -- [`SourceScope`] identifies a name scope in the original source code. +- [`SourceScope`] identifies a name scope in the original source code. Used for + diagnostics and for debuginfo in debuggers. -- [`Promoted`] identifies a promoted constant (related to const evaluation). +- [`Promoted`] identifies a promoted constant within another item (related to + const evaluation). Note: it is unique only locally within the item; + [`GlobalId`] must be used if you need to *globally* identify the promoted. - [`GlobalId`] identifies a global variable: a `const`, a `static`, a `const fn` where all arguments are [zero-sized types], or a promoted constant. From 280e4e769a79c6ba6242b58f75b9bf5703e5a978 Mon Sep 17 00:00:00 2001 From: Camelid Date: Mon, 23 Nov 2020 15:04:30 -0800 Subject: [PATCH 5/7] Note how you can retrieve the associated data Suggested by @LeSeulArtichaut. --- src/identifiers.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/identifiers.md b/src/identifiers.md index 9e89d21c3..7a15747c4 100644 --- a/src/identifiers.md +++ b/src/identifiers.md @@ -64,16 +64,20 @@ See the [HIR chapter][hir-map] for more detailed information. ## In the MIR - [`BasicBlock`] identifies a *basic block*. It points to an instance of - [`BasicBlockData`]. + [`BasicBlockData`], which can be retrieved by indexing into + [`Body::basic_blocks()`] (note that you must call a function; the field is + private). - [`Local`] identifies a local variable in a function. Its associated data is in - [`LocalDecl`]. + [`LocalDecl`], which can be retrieved by indexing into [`Body.local_decls`]. - [`Field`] identifies a struct's, union's, or enum variant's field. It is used as a "projection" in [`Place`]. - [`SourceScope`] identifies a name scope in the original source code. Used for - diagnostics and for debuginfo in debuggers. + diagnostics and for debuginfo in debuggers. It points to an instance of + [`SourceScopeData`], which can be retrieved by indexing into + [`Body.source_scopes`]. - [`Promoted`] identifies a promoted constant within another item (related to const evaluation). Note: it is unique only locally within the item; @@ -88,11 +92,15 @@ See the [HIR chapter][hir-map] for more detailed information. [`BasicBlock`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.BasicBlock.html [`BasicBlockData`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.BasicBlockData.html +[`Body::basic_blocks()`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#method.basic_blocks [`Local`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Local.html [`LocalDecl`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.LocalDecl.html +[`Body.local_decls`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#structfield.local_decls [`Field`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Field.html [`Place`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Place.html [`SourceScope`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.SourceScope.html +[`SourceScopeData`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.SourceScopeData.html +[`Body.source_scopes`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#structfield.source_scopes [`Promoted`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Promoted.html [`GlobalId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/struct.GlobalId.html [`Location`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Location.html From fa415c6abd07100b6401203b2a9194d772c03502 Mon Sep 17 00:00:00 2001 From: Oli Scherer Date: Fri, 27 Nov 2020 17:47:39 +0100 Subject: [PATCH 6/7] Update src/identifiers.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Léo Lanteri Thauvin --- src/identifiers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/identifiers.md b/src/identifiers.md index 7a15747c4..c5f8e0d70 100644 --- a/src/identifiers.md +++ b/src/identifiers.md @@ -80,7 +80,7 @@ See the [HIR chapter][hir-map] for more detailed information. [`Body.source_scopes`]. - [`Promoted`] identifies a promoted constant within another item (related to - const evaluation). Note: it is unique only locally within the item; + const evaluation). Note: it is unique only locally within the item, so it should be associated with a `DefId`; [`GlobalId`] must be used if you need to *globally* identify the promoted. - [`GlobalId`] identifies a global variable: a `const`, a `static`, a `const fn` From 2ab7163b17cc94f217c1828a236185cafa183c4c Mon Sep 17 00:00:00 2001 From: Camelid Date: Mon, 7 Dec 2020 11:50:52 -0800 Subject: [PATCH 7/7] Add TODO for `Promoted` re `GlobalId` --- src/identifiers.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/identifiers.md b/src/identifiers.md index c5f8e0d70..3923c9332 100644 --- a/src/identifiers.md +++ b/src/identifiers.md @@ -80,8 +80,9 @@ See the [HIR chapter][hir-map] for more detailed information. [`Body.source_scopes`]. - [`Promoted`] identifies a promoted constant within another item (related to - const evaluation). Note: it is unique only locally within the item, so it should be associated with a `DefId`; - [`GlobalId`] must be used if you need to *globally* identify the promoted. + const evaluation). Note: it is unique only locally within the item, so it + should be associated with a `DefId`. + [`GlobalId`] will give you a more specific identifier (TODO). - [`GlobalId`] identifies a global variable: a `const`, a `static`, a `const fn` where all arguments are [zero-sized types], or a promoted constant.