update documentation

Author: dingxiangfei2009

compiler/rustc_middle/src/mir/mod.rs

@@ -334,7 +334,14 @@ pub struct Body<'tcx> {
     #[type_visitable(ignore)]
     pub function_coverage_info: Option<Box<coverage::FunctionCoverageInfo>>,
 
-    /// Coroutine local-upvar map
+    /// Coroutine local-upvar map, which maps the coroutine captures as fields
+    /// in coroutine state to the internal MIR locals.
+    /// This is to help borrow-checker assert lifetime invariance between types of
+    /// the capture, as appear exterior to the coroutine, and that of locals,
+    /// intto which the captures are relocated.
+    /// It also assists diagnostic to re-construct the identity of the captures.
+    /// MIR interpretation and instrumentation can disregard this information.
+    /// It carries no operation-semantic significance.
     pub local_upvar_map: IndexVec<FieldIdx, Option<Local>>,
 }
 

compiler/rustc_mir_transform/src/coroutine/relocate_upvars.rs

@@ -29,10 +29,57 @@
 //!
 //! Each place that starts with access into the coroutine structure `_1` is replaced with the fresh local as
 //! the base.
-//! For instance, `(_1.4 as Some).0` is rewritten into `(_34 as Some).0` when `_34` is the fresh local
-//! corresponding to the captured upvar stored in `_1.4`.
+//! Suppose we are to lower this coroutine into the MIR.
+//! ```ignore (illustrative)
+//! let mut captured = None;
+//! let _ = #[coroutine] || {
+//!     yield ();
+//!     if let Some(inner) = &mut captured {
+//!         *inner = 42i32; // (*)
+//!     }
+//! };
+//! ```
+//! `captured` is the only capture, whose mutable borrow is formally alotted to the first field `_1.0: &mut i32`.
+//! The highlighted line `(*)` should be lowered, roughly, into MIR `(*_1.0) = const 42i32;`.
+//! Now, by application of this pass, we create a new local `_4: &mut i32` and we perform the following
+//! code transformation.
+//!
+//! A new block is constructed to just perform the relocation of this mutable borrow.
+//! This block is inserted to the very beginning of the coroutine body control flow,
+//! so that this is executed before any proper coroutine code as it transits from `UNRESUME` state to
+//! any other state.
+//! This "prologue" will look like the following.
+//! ```ignore (illustrative)
+//! StorageLive(_5);
+//! StorageLive(_4);
+//! _5 = move (_1.0);
+//! _4 = move (_5);
+//! StorageDead(_5);
+//! ```
+//! Note that we also create a trampoline local `_5` of the same type.
+//!
+//! ### Intricacy around the trampoline local
+//! The reason that we need the trampolines is because state transformation and coroutine
+//! layout calculation is not aware of potential storage conflict between captures as struct fields
+//! and other saved locals.
+//! The only guarantee that we can work with is one where any coroutine layout calculator respects
+//! the storage conflict constracts between *MIR locals*.
+//! It is known that calculators do not consider struct fields, where captures reside, as MIR locals.
+//! This is the source of potential memory overlaps.
+//! For instance, in a hypothetical situation,
+//! - `_1.0` is relocated to `_4`;
+//! - `_1.1` is relocated to `_6`;
+//! - `_4` and `_6` remains live at one of the first suspension state;
+//! - `_4` occupies the same offset of `_1.1` and `_6` occupies the same offset of `_1.0`
+//!   as decided by some layout calculator;
+//! In this scenario, without trampolining, the relocations introduce undefined behaviour.
+//!
+//! As a proposal for a future design, it is best that coroutine captures receive their own
+//! MIR locals, possibly in a form of "function arguments" like `_1` itself.
+//! The trampolining transformation already attempts to restore the semantics of MIR locals to
+//! these captures and promoting them to "arguments" would make MIR safer to handle.
 //!
-//! This phase assumes that the initial built MIR respects the nature of captures.
+//! One should note that this phase assumes that the initial built MIR respects the nature of captures.
 //! For instance, if the upvar `_1.4` is instead a by-ref-mut capture of a value of type `T`,
 //! this phase assumes that all access correctly built as operating on the place `(*_1.4)`.
 //! Based on the assumption, this phase replaces `_1.4` with a fresh local `_34: &mut T` and