Merge pull request #42092 from slavapestov/rqm-even-more-comments

RequirementMachine: More comments and a regression test for a long-ago fixed crasher

Author: slavapestov

lib/AST/RequirementMachine/GenericSignatureQueries.cpp

@@ -10,8 +10,25 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// Implements the various operations on interface types in GenericSignature.
-// Use those methods instead of calling into the RequirementMachine directly.
+// The various generic signature query operations on GenericSignature will
+// lazily construct a requirement machine for the generic signature from the
+// RewriteContext, then call the methods in this file.
+//
+// If you're working elsewhere in the compiler, use the methods on
+// GenericSignature instead of calling into the RequirementMachine directly.
+//
+// Each query is generally implemented in the same manner:
+//
+// - First, convert the subject type parameter into a Term.
+// - Simplify the Term to obtain a canonical Term.
+// - Perform a property map lookup on the Term.
+// - Return the appropriate piece of information from the property map.
+//
+// A few are slightly different; for example, getCanonicalTypeInContext() takes
+// an arbitrary type, not just a type parameter, and recursively transforms the
+// type parameters it contains, if any.
+//
+// Also, getConformanceAccessPath() is another one-off operation.
 //
 //===----------------------------------------------------------------------===//
 

lib/AST/RequirementMachine/HomotopyReduction.cpp

@@ -19,9 +19,11 @@
 // 2) Small enough that no further rules can be deleted without changing the
 //    resulting confluent rewrite system.
 //
-// Redundant rules that are not part of the minimal set are redundant are
-// detected by analyzing the set of rewrite loops computed by the completion
-// procedure. See RewriteLoop.cpp for a discussion of rewrite loops.
+// The main entry point here is RewriteSystem::minimizeRewriteSystem().
+//
+// Redundant rules are detected by analyzing the set of rewrite loops computed
+// by the completion procedure. See RewriteLoop.cpp for a discussion of rewrite
+// loops.
 //
 // If a rewrite rule appears exactly once in a loop and without context, the
 // loop witnesses a redundancy; the rewrite rule is equivalent to traveling

lib/AST/RequirementMachine/InterfaceType.cpp

@@ -13,6 +13,28 @@
 // This file implements routines for converting Swift AST interface types to
 // rewrite system terms.
 //
+// A type parameter in Swift is a GenericTypeParamType wrapped in zero or
+// more DependentMemberTypes. DependentMemberTypes come in two flavors,
+// "unresolved" and "resolved". Unresolved DependentMemberTypes store an
+// identifier. Resolved DependentMemberTypes store an associated type
+// declaration.
+//
+// In the rewrite system, unresolved DependentMemberTypes map to name symbols;
+// resolved DependentMemberTypes map to associated type symbols.
+//
+// The mapping of the root generic parameter depends on the specific usage:
+//
+// - If the type is understood to be the subject type of a requirement in a
+//   protocol, the root generic parameter, which must equal τ_0_0, maps to a
+//   protocol symbol for the protocol in question.
+//
+// - If the type is part of a top-level generic signature, the root generic
+//   parameter maps to the corresponding generic parameter symbol.
+//
+// - If the type was derived from a superclass or concrete type symbol, the
+//   root generic parameter, which must equal τ_0_N for some N, maps to the
+//   Nth substitution stored in the superclass or concrete type symbol.
+//
 // The rewrite system's reduction order differs from the canonical type order
 // used by Swift's ABI and name mangling. What this means in practice is that
 // converting a canonical type to a term does not necessarily produce a
@@ -36,6 +58,43 @@
 // their module names, if the unqualified names are the same). In the reduction
 // order, we want P1 < P2 to also hold if P1 inherits from P2.
 //
+// The following diagram shows the relationship between the two directions of
+// the type to term mapping:
+//
+//      ---------------------
+//     / Non-canonical Type /
+//     ---------------------
+//               |
+//               v
+//     +------------------+
+//     | getTermForType() |
+//     +------------------+
+//               |
+//               v
+//     ---------------------
+//    / Non-canonical Term /
+//    ---------------------
+//               |
+//               v
+//        +------------+
+//        | simplify() |
+//        +------------+
+//               |
+//               v
+//       -----------------
+//      / Canonical Term /
+//      -----------------
+//               |
+//               v
+//     +------------------+
+//     | getTypeForTerm() |
+//     +------------------+
+//               |
+//               v
+//       -----------------
+//      / Canonical Type /
+//      -----------------
+//
 //===----------------------------------------------------------------------===//
 
 #include "swift/AST/Decl.h"

lib/AST/RequirementMachine/RequirementBuilder.cpp

@@ -13,6 +13,11 @@
 // This file implements the final step in generic signature minimization,
 // building requirements from a set of minimal, canonical rewrite rules.
 //
+// The main entry point is RequirementMachine::buildRequirementsFromRules(),
+// called from the RequirementSignatureRequest, AbstractGenericSignatureRequest
+// and InferredGenericSignatureRequest requests defined in
+// RequirementMachineRequests.cpp.
+//
 //===----------------------------------------------------------------------===//
 
 #include "RequirementMachine.h"

lib/AST/RequirementMachine/RewriteContext.cpp

@@ -151,7 +151,8 @@
 using namespace swift;
 using namespace rewriting;
 
-/// Build a DebugOptions by parsing a comma-separated list of debug flags.
+/// Parse a comma-separated list from the -debug-requirement-machine= frontend
+/// flag.
 static DebugOptions parseDebugFlags(StringRef debugFlags) {
   DebugOptions result;
 

validation-test/compiler_crashers_2_fixed/sr10792.swift

@@ -0,0 +1,8 @@
+// RUN: %target-swift-frontend -emit-ir %s
+
+protocol DateGroupedCollection: Collection {
+  typealias DictionaryType = [String: Int]
+
+  typealias Index = DictionaryType.Index
+  typealias Element = DictionaryType.Element
+}