add comments

Author: lcnr

compiler/rustc_infer/src/infer/snapshot/check_leaks.rs

@@ -4,6 +4,9 @@ use rustc_middle::ty::{self, Ty, TyCtxt};
 use rustc_middle::ty::{TypeSuperVisitable, TypeVisitor};
 use std::ops::ControlFlow;
 
+/// Check for leaking inference variables and placeholders
+/// from snapshot. This is only used if `debug_assertions`
+/// are enabled.
 pub struct HasSnapshotLeaksVisitor {
     universe: ty::UniverseIndex,
     variable_lengths: VariableLengths,

compiler/rustc_infer/src/infer/snapshot/fudge.rs

@@ -98,6 +98,12 @@ impl<'tcx> InferCtxt<'tcx> {
     }
 }
 
+/// To avoid leaking inference variables from snapshots, fudge inference
+/// by replacing inference variables from the snapshot with fresh ones
+/// created outside of it.
+///
+/// To see how this works, check out the documentation of the [`FudgeInference`]
+/// wrapper used by [`fn InferCtxt::fudge_inference_if_ok`].
 #[macro_export]
 macro_rules! fudge_vars_no_snapshot_leaks {
     ($tcx:lifetime, $t:ty) => {
@@ -136,13 +142,22 @@ macro_rules! fudge_vars_no_snapshot_leaks {
     };
 }
 
+/// When rolling back a snapshot, replaces inference variables in `T` created
+/// during the snapshot with new inference variables created afterwards.
 struct FudgeInference<T>(T);
 impl<'tcx, T: TypeFoldable<TyCtxt<'tcx>>> NoSnapshotLeaks<'tcx> for FudgeInference<T> {
     type StartData = VariableLengths;
     type EndData = (T, Option<InferenceFudgeData>);
+
+    /// Store which inference variables already exist at the start
+    /// of the snapshot.
     fn snapshot_start_data(infcx: &InferCtxt<'tcx>) -> Self::StartData {
         infcx.variable_lengths()
     }
+    /// At the end of the snapshot, fetch the metadata for all variables
+    /// created during the snapshot. As these variables get discarded during
+    /// rollback, we have to get this information before rollback and use it
+    /// to create new inference variables after.
     fn end_of_snapshot(
         infcx: &InferCtxt<'tcx>,
         FudgeInference(value): FudgeInference<T>,
@@ -154,6 +169,9 @@ impl<'tcx, T: TypeFoldable<TyCtxt<'tcx>>> NoSnapshotLeaks<'tcx> for FudgeInferen
             (value, None)
         }
     }
+    /// Using the metadata fetched in `fn end_of_snapshot`, replace all leaking
+    /// inference variables with new ones, reusing the metadata of the leaked
+    /// variables.
     fn avoid_leaks(infcx: &InferCtxt<'tcx>, (value, fudge_data): Self::EndData) -> Self {
         if let Some(fudge_data) = fudge_data {
             FudgeInference(fudge_data.fudge_inference(infcx, value))
@@ -163,6 +181,8 @@ impl<'tcx, T: TypeFoldable<TyCtxt<'tcx>>> NoSnapshotLeaks<'tcx> for FudgeInferen
     }
 }
 
+/// At the end of a snpashot, right before rollback, remember all newly created
+/// inference variables and their metadata.
 pub struct InferenceFudgeData {
     type_vars: (Range<TyVid>, Vec<TypeVariableOrigin>),
     int_vars: Range<IntVid>,
@@ -210,6 +230,10 @@ impl InferenceFudgeData {
     }
 }
 
+/// Using the `InferenceFudgeData` created right before rollback, replace
+/// all leaked inference variables of the snapshot with newly created ones.
+///
+/// This is used after the snapshot has already been rolled back.
 struct InferenceFudger<'a, 'tcx> {
     infcx: &'a InferCtxt<'tcx>,
     data: InferenceFudgeData,

compiler/rustc_infer/src/infer/snapshot/mod.rs

@@ -138,6 +138,22 @@ pub struct VariableLengths {
     const_vars: usize,
 }
 
+/// When rolling back a snapshot, we discard all inference constraints
+/// added during that snapshot. We also completely remove any inference
+/// variables created during the snapshot. Leaking these inference
+/// variables from the snapshot and later using them can then result
+/// either in an ICE or even accidentally reuse a newly created, totally
+/// separate, inference variable.
+///
+/// To avoid this we make sure that when rolling back snapshots in
+///  `fn probe` and `fn commit_if_ok` we do not return any inference
+/// variables created during this snapshot.
+///
+/// This has a fairly involved setup as we previously did not check this
+/// and now rely on leaking inference variables, e.g. via `TypeError`.
+/// To still avoid ICE we now "fudge inference" in these cases, replacing
+/// any newly created inference variables from inside the snapshot with
+/// new inference variables created outside of it.
 pub trait NoSnapshotLeaks<'tcx> {
     type StartData;
     type EndData;
@@ -150,6 +166,16 @@ pub trait NoSnapshotLeaks<'tcx> {
     fn avoid_leaks(infcx: &InferCtxt<'tcx>, data: Self::EndData) -> Self;
 }
 
+/// A trait implemented by types which cannot contain any inference variables
+/// which could be leaked. The [`NoSnapshotLeaks`] impl for these types is
+/// trivial.
+///
+/// You can mostly think of this as if it is an auto-trait with negative
+/// impls for `Region`, `Ty` and `Const` and a positive impl for `Canonical`.
+/// Actually using an auto-trait instead of manually implementing it for
+/// all types of interest results in overlaps during coherence. Not using
+/// auto-traits will also make it easier to share this code with Rust Analyzer
+/// in the future, as they want to avoid any unstable features.
 pub trait TrivialNoSnapshotLeaks<'tcx> {}
 impl<'tcx, T: TrivialNoSnapshotLeaks<'tcx>> NoSnapshotLeaks<'tcx> for T {
     type StartData = ();