[ConstraintGraph] NFC: Clarify names of inference APIs and add comments

Author: xedin

include/swift/Sema/ConstraintGraph.h

@@ -119,12 +119,35 @@ class ConstraintGraphNode {
   /// Remove a type variable which used to reference this type variable.
   void removeReferencedBy(TypeVariableType *typeVar);
 
-  /// Experimental {
-  void introduceToInference(Constraint *constraint, bool notifyFixedBindings);
-  void retractFromInference(Constraint *constraint, bool notifyFixedBindings);
-  void reintroduceToInference(Constraint *constraint, bool notifyFixedBindings);
+  /// Binding Inference {
+
+  /// Infer bindings from the given constraint and notify referenced variables
+  /// about its arrival (if requested). This happens every time a new constraint
+  /// gets added to a constraint graph node.
+  void introduceToInference(Constraint *constraint, bool notifyReferencedVars);
+
+  /// Forget about the given constraint. This happens every time a constraint
+  /// gets removed for a constraint graph.
+  void retractFromInference(Constraint *constraint, bool notifyReferencedVars);
+
+  /// Re-evaluate the given constraint. This happens when there are changes
+  /// in associated type variables e.g. bound/unbound to/from a fixed type,
+  /// equivalence class changes.
+  void reintroduceToInference(Constraint *constraint, bool notifyReferencedVars);
+
+  /// Drop all previously collected bindings and re-infer based on the
+  /// current set constraints associated with this equivalence class.
   void resetBindingSet();
-  void updateAdjacentVars() const;
+
+  /// Notify all of the type variables that have this one (or any member of
+  /// its equivalence class) referenced in their fixed type.
+  ///
+  /// This is a traversal up the reference change which triggers constraint
+  /// re-introduction to affected type variables.
+  ///
+  /// This is useful in situations when type variable gets bound and unbound,
+  /// or equivalence class changes.
+  void notifyReferencingVars() const;
   /// }
 
   /// The constraint graph this node belongs to.

lib/Sema/ConstraintGraph.cpp

@@ -138,7 +138,7 @@ void ConstraintGraphNode::removeConstraint(Constraint *constraint) {
   Constraints.pop_back();
 }
 
-void ConstraintGraphNode::updateAdjacentVars() const {
+void ConstraintGraphNode::notifyReferencingVars() const {
   SmallVector<TypeVariableType *, 4> stack;
 
   stack.push_back(TypeVar);
@@ -161,7 +161,7 @@ void ConstraintGraphNode::updateAdjacentVars() const {
 
         if (!repr->getImpl().getFixedType(/*record=*/nullptr))
           CG[repr].reintroduceToInference(constraint,
-                                          /*notifyFixedBindings=*/false);
+                                          /*notifyReferencedVars=*/false);
       }
     }
   };
@@ -210,10 +210,10 @@ void ConstraintGraphNode::addToEquivalenceClass(
       auto &node = CG[newMember];
 
       for (auto *constraint : node.getConstraints()) {
-        introduceToInference(constraint, /*notifyFixedBindings=*/true);
+        introduceToInference(constraint, /*notifyReferencedVars=*/true);
       }
 
-      node.updateAdjacentVars();
+      node.notifyReferencingVars();
     }
   }
 }
@@ -237,7 +237,7 @@ void ConstraintGraphNode::truncateEquivalenceClass(unsigned prevSize) {
 
     // Re-infer bindings all all of the newly made representatives.
     for (auto *typeVar : disconnectedVars)
-      CG[typeVar].updateAdjacentVars();
+      CG[typeVar].notifyReferencingVars();
   }
 }
 
@@ -288,51 +288,51 @@ static bool isUsefulForReferencedVars(Constraint *constraint) {
 }
 
 void ConstraintGraphNode::introduceToInference(Constraint *constraint,
-                                               bool notifyFixedBindings) {
+                                               bool notifyReferencedVars) {
   if (forRepresentativeVar()) {
     auto fixedType = TypeVar->getImpl().getFixedType(/*record=*/nullptr);
     if (!fixedType || fixedType->isTypeVariableOrMember())
       getCurrentBindings().infer(constraint);
   } else {
     auto *repr =
         getTypeVariable()->getImpl().getRepresentative(/*record=*/nullptr);
-    CG[repr].introduceToInference(constraint, /*notifyFixedBindings=*/false);
+    CG[repr].introduceToInference(constraint, /*notifyReferencedVars=*/false);
   }
 
-  if (!notifyFixedBindings || !isUsefulForReferencedVars(constraint))
+  if (!notifyReferencedVars || !isUsefulForReferencedVars(constraint))
     return;
 
   for (auto *fixedBinding : getReferencedVars()) {
     CG[fixedBinding].introduceToInference(constraint,
-                                          /*notifyFixedBindings=*/false);
+                                          /*notifyReferencedVars=*/false);
   }
 }
 
 void ConstraintGraphNode::retractFromInference(Constraint *constraint,
-                                               bool notifyFixedBindings) {
+                                               bool notifyReferencedVars) {
   if (forRepresentativeVar()) {
     auto fixedType = TypeVar->getImpl().getFixedType(/*record=*/nullptr);
     if (!fixedType || fixedType->isTypeVariableOrMember())
       getCurrentBindings().retract(constraint);
   } else {
     auto *repr =
         getTypeVariable()->getImpl().getRepresentative(/*record=*/nullptr);
-    CG[repr].retractFromInference(constraint, /*notifyFixedBindings=*/false);
+    CG[repr].retractFromInference(constraint, /*notifyReferencedVars=*/false);
   }
 
-  if (!notifyFixedBindings || !isUsefulForReferencedVars(constraint))
+  if (!notifyReferencedVars || !isUsefulForReferencedVars(constraint))
     return;
 
   for (auto *fixedBinding : getReferencedVars()) {
     CG[fixedBinding].retractFromInference(constraint,
-                                          /*notifyFixedBindings=*/false);
+                                          /*notifyReferencedVars=*/false);
   }
 }
 
 void ConstraintGraphNode::reintroduceToInference(Constraint *constraint,
-                                                 bool notifyFixedBindings) {
-  retractFromInference(constraint, notifyFixedBindings);
-  introduceToInference(constraint, notifyFixedBindings);
+                                                 bool notifyReferencedVars) {
+  retractFromInference(constraint, notifyReferencedVars);
+  introduceToInference(constraint, notifyReferencedVars);
 }
 
 void ConstraintGraphNode::resetBindingSet() {
@@ -557,8 +557,9 @@ void ConstraintGraph::bindTypeVariable(TypeVariableType *typeVar, Type fixed) {
       // Newly referred vars need to re-introduce all constraints associated
       // with this type variable.
       for (auto *constraint : (*this)[typeVar].getConstraints()) {
-        otherNode.reintroduceToInference(constraint,
-                                         /*notifyFixedBindings=*/false);
+        if (isUsefulForReferencedVars(constraint))
+          otherNode.reintroduceToInference(constraint,
+                                           /*notifyReferencedVars=*/false);
       }
     }
   }
@@ -568,7 +569,7 @@ void ConstraintGraph::bindTypeVariable(TypeVariableType *typeVar, Type fixed) {
   // whole equivalence class of the current type variable and all of its
   // fixed bindings.
   {
-    (*this)[typeVar].updateAdjacentVars();
+    (*this)[typeVar].notifyReferencingVars();
   }
 }
 
@@ -580,7 +581,7 @@ void ConstraintGraph::unbindTypeVariable(TypeVariableType *typeVar, Type fixed)
   {
     auto &node = (*this)[typeVar];
 
-    node.updateAdjacentVars();
+    node.notifyReferencingVars();
 
     llvm::SmallPtrSet<TypeVariableType *, 4> typeVars;