EscapeAnalysis: rework graph update and merge algorithms

The two major take aways from this patch are:

(1) Impose graph structure and reduce superfluous nodes and edges.

Incrementally make the connection graph and the APIs used to construct
it more structured.

_This allows node properties based on the SILValue to be reliably added to nodes_

Although that was the initial motiviation, there are other
benefits. Non-content nodes now have verifiable SILValues. Content
nodes now have meaningful SILValues even though they can't be
guaranteed due to merging. As a result it is *much* easier to debug
the graph and correlate it with the SIL. Rather than a web of
connection graph nodes with no identity and edges that don't
correspond to anything in SIL, the graph nodes now have value number
that correspond to the instruction used to dereference the node. The
edges also exhibit structure now. A pointsTo edge now (in practice)
always corresponds to a real pointer deference in the SIL. Doing this
required more than just adding some helpers, it was also necessary to
rewrite the graph merge and update algorithms.

(2) Split up underlying functionality into more explicit steps

Breaks apart the most complex parts of the graph algorithms into small
self-contained, self-checked steps. The purpose of each step is clear
and it's possible to reason about correctness from basic
invariants. Each merge step can now run full graph verification.

This was also done to move toward an invariant that the graph is never
mutated during a query. But to finish that goal, we need to add a
use-point query. With that, there will be no node creation, use point
propagation, new defer edges, etc. after graph building. At the very
least, this will make it sane to debug the output of the analysis.

---
Here is a change-by-change description in diff order:

Replace `updatePointsTo` with `initializePointsTo` and
`mergePointsTo`. Merging is very simple on its own. Initialization
requires some extra consideration for graph invariants. This
separation makes it possible to write stong asserts and to
independently reason about the correctness of each step based on
static invariants.

Replace `getContentNode` with `createContentNode`, and add two higher
level APIs `createMergedContent`, and `getFieldContent`. This makes
explicit the important cases of merging nodes and creating a special
nodes for class fields. This slightly simplifies adding properties to
content nodes and helps understand the structure of the graph.

Factor out an `escapeContentsOf` helper for use elsewhere...

Add a `getValueContent` helper. This is where we can tie the
properties of content nodes to the address values that are used to
address that content. This now also ensures that a Value node's
value field is consistent with all SILValues that map to it.

Add -escapes-internal-verify to check that the graph is in a valid
state after every merge or update step. This verification drove the
partial rewrite of mergeAllScheduledNodes.

ConnectionGraph::defer implementation: explictly handle the three
possible cases of pointsTo initialization or pointsTo merging at the
top level, so that those underlying implementations do not need to
dynamically handle weirdly different scenarios.

ConnectionGraph::initializePointsTo implementation: this simplified
implementation is possible by relying on invariants that can be
checked at each merge/update step. The major functional difference is
that it avoids creating unnecessary pointsTo edges. The previous
implementation often created pointsTo edges when adding defer edges
just to be conservative. Fixing this saved my sanity during debugging
because the pointsTo edges now always correspond to a SIL operations
that dereference the pointer. I'm also arguing without evidence that
this should be much more efficient.

ConnectionGraph::mergeAllScheduledNodes implementation: Add
verification to each step so that we can prove the other utilities
that are used while merging aren't making incorrect assumptions about
the graph state. Remove checks for merged nodes now that the graph is
consistently valid. Also remove a loop at the end that didn't seem to
do anything. The diff is impossible to review, but the idea is
basically the same. As long as it's still possible to scan through the
steps in the new code without getting totally lost, then the goal was
achieved.

ConnectionGraph::mergePointsTo: This is extremely simple now. In all
the places where we used to call updatePointsTo, and now call
mergePointsTo, it's a lot easier for someone debugging the code to
reason about what could possibly happen at that point.

`createMergedContent` is a placeholder for transferring node properties.

The `getFieldContent` helper may seem silly, but I find it helpful to
see all the important ways that content can be created in one place
next to the createContentNode, and I like the way that the creation of
the special "field content" node is more explicit in the source.

ConnectionGraph::mergeFrom implementation: this is only a minor
cleanup to remove some control flow nesting and use the CGNodeWorklist
abstraction.

In AnalyzeInstruction, add EscapeAnalysis::getValueContent helper. It
eliminates an extra step of going through the value node to get at its
content node. This is where we can derive content node properties from
the SILValue that dereferences the content. We can update the content
node's associated value 'V' if it's useful. It's also a place to put
assertions specific to the first level of content.

In AnalyzeInstruction, Array semantic calls: add support for
getValueContent so we can derive node properties. This is also nice
because it's explicit about which nodes are value content vs. field
content.

In AnalyzeInstruction, cleanup Release handling: use the explicit
APIs: getValueContent, getFieldContent, and escapeContentsOf.

In AnalyzeInstruction, assert that load-like things can't produce addresses.

In AnalyzeInstruction, add comments to clarify object projection handling.

In AnalyzeInstruction, add comments to explain store handling.

In AnalyzeInstruction, drop the assumption that all partial applies hold pointers.

In AnalyzeInstruction, handle aggregates differently so that Value
nodes are always consistent with their SILValue and can be
verified. Aggregates nodes are still coalesced if they only have a
single pointer-type subelement. If we arbitrarily coalesced an
aggregate with just one of its subelements then there would be no
consistent way to identify the value that corresponds to a connection
graph node.

Author: atrick

include/swift/SILOptimizer/Analysis/EscapeAnalysis.h

@@ -403,17 +403,7 @@ class EscapeAnalysis : public BottomUpIPAnalysis {
 
     /// Checks an invariant of the connection graph: The points-to nodes of
     /// the defer-successors must match with the points-to of this node.
-    bool matchPointToOfDefers() const {
-      for (CGNode *Def : defersTo) {
-        if (pointsTo != Def->pointsTo)
-          return false;
-      }
-      /// A defer-path in the graph must not end without the specified points-to
-      /// node.
-      if (pointsTo && !pointsToIsEdge && defersTo.empty())
-        return false;
-      return true;
-    }
+    bool matchPointToOfDefers(bool allowMerge = false) const;
 
     friend class CGNodeMap;
     friend class ConnectionGraph;
@@ -480,7 +470,7 @@ class EscapeAnalysis : public BottomUpIPAnalysis {
       llvm_unreachable("Unhandled EscapeState in switch.");
     }
 
-    /// Returns the content node if of this node if it exists in the graph.
+    /// Returns the content node of this node if it exists in the graph.
     CGNode *getContentNodeOrNull() const {
       return pointsTo;
     }
@@ -603,14 +593,25 @@ class EscapeAnalysis : public BottomUpIPAnalysis {
       }
     }
 
+    /// Initialize the 'pointsTo' fields of all nodes in the defer web of \p
+    /// initialiNode.
+    ///
+    /// If \p createEdge is true, a proper pointsTo edge will be created from \p
+    /// initialNode to \p pointsTo.
+    void initializePointsTo(CGNode *initialNode, CGNode *newPointsTo,
+                            bool createEdge = false);
+
+    void initializePointsToEdge(CGNode *initialNode, CGNode *newPointsTo) {
+      initializePointsTo(initialNode, newPointsTo, true);
+    }
+
     /// Merges all nodes which are added to the ToMerge list.
     void mergeAllScheduledNodes();
 
-    /// Transitively updates pointsTo of all nodes in the defer-edge web,
-    /// starting at \p InitialNode.
-    /// If a node in the web already points to another content node, the other
-    /// content node is scheduled to be merged with \p pointsTo.
-    void updatePointsTo(CGNode *InitialNode, CGNode *pointsTo);
+    /// Transitively update pointsTo of all nodes in the defer-edge web,
+    /// reaching and reachable from \p initialNode. All nodes in this defer web
+    /// must already have an initialized `pointsTo`.
+    void mergePointsTo(CGNode *initialNode, CGNode *pointsTo);
 
     /// Utility function to clear the isInWorkList flags of all nodes in
     /// \p WorkList.
@@ -627,12 +628,20 @@ class EscapeAnalysis : public BottomUpIPAnalysis {
     /// Returns null, if V is not a "pointer".
     CGNode *getNode(ValueBase *V, bool createIfNeeded = true);
 
-    /// Gets or creates a content node to which \a AddrNode points to during
-    /// initial graph construction. This may not be called after defer edges
-    /// have been created. Doing so would break the invariant that all
-    /// non-content nodes ultimately have a pointsTo edge to a single content
-    /// node.
-    CGNode *getContentNode(CGNode *AddrNode);
+    /// Helper to create a content node and update the pointsTo graph. \p
+    /// addrNode will point to the new content node. The new content node is
+    /// directly initialized with the remaining function arguments.
+    CGNode *createContentNode(CGNode *addrNode, SILValue addrVal);
+
+    /// Create a new content node based on an existing content node to support
+    /// graph merging.
+    ///
+    /// \p destAddrNode will point to to new content. The content's initial
+    /// state will be initialized based on the \p srcContent node.
+    CGNode *createMergedContent(CGNode *destAddrNode, CGNode *srcContent);
+
+    /// Get a node represnting the field data within the given RC node.
+    CGNode *getFieldContent(CGNode *rcNode);
 
     /// Get or creates a pseudo node for the function return value.
     CGNode *getReturnNode() {
@@ -679,31 +688,21 @@ class EscapeAnalysis : public BottomUpIPAnalysis {
       return Idx;
     }
 
-    /// Specifies that the node's value escapes to global or unidentified
-    /// memory.
-    void setEscapesGlobal(CGNode *Node) {
-      Node->mergeEscapeState(EscapeState::Global);
-
-      // Make sure to have a content node. Otherwise we may end up not merging
-      // the global-escape state into a caller graph (only content nodes are
-      // merged). Either the node itself is a content node or we let the node
-      // point to one.
-      if (Node->Type != NodeType::Content)
-        getContentNode(Node);
+    void escapeContentsOf(CGNode *Node) {
+      CGNode *escapedContent = Node->getContentNodeOrNull();
+      if (!escapedContent) {
+        escapedContent = createContentNode(Node, Node->V);
+      }
+      escapedContent->markEscaping();
     }
 
     /// Creates a defer-edge between \p From and \p To.
     /// This may trigger node merges to keep the graph invariance 4).
     /// Returns the \p From node or its merge-target in case \p From was merged
     /// during adding the edge.
-    /// The \p EdgeAdded is set to true if there was no defer-edge between
-    /// \p From and \p To, yet.
-    CGNode *defer(CGNode *From, CGNode *To, bool &EdgeAdded) {
-      if (addDeferEdge(From, To))
-        EdgeAdded = true;
-      mergeAllScheduledNodes();
-      return From->getMergeTarget();
-    }
+    /// \p Changed is set to true if a defer edge was added or any nodes were
+    /// merged.
+    CGNode *defer(CGNode *From, CGNode *To, bool &Changed);
 
     /// Creates a defer-edge between \p From and \p To.
     /// This may trigger node merges to keep the graph invariance 4).
@@ -802,7 +801,7 @@ class EscapeAnalysis : public BottomUpIPAnalysis {
     void dumpCG() const;
 
     /// Checks if the graph is OK.
-    void verify() const;
+    void verify(bool allowMerge = false) const;
 
     /// Just verifies the graph structure. This function can also be called
     /// during the graph is modified, e.g. in mergeAllScheduledNodes().
@@ -889,9 +888,22 @@ class EscapeAnalysis : public BottomUpIPAnalysis {
   SILValue getPointerRoot(SILValue value) const;
 
   /// If \p pointer is a pointer, set it to global escaping.
-  void setEscapesGlobal(ConnectionGraph *ConGraph, ValueBase *pointer) {
-    if (CGNode *Node = ConGraph->getNode(pointer))
-      ConGraph->setEscapesGlobal(Node);
+  void setEscapesGlobal(ConnectionGraph *conGraph, ValueBase *pointer) {
+    CGNode *Node = conGraph->getNode(pointer);
+    if (!Node)
+      return;
+
+    if (Node->isContent()) {
+      Node->markEscaping();
+      return;
+    }
+    Node->mergeEscapeState(EscapeState::Global);
+
+    // Make sure to have a content node. Otherwise we may end up not merging
+    // the global-escape state into a caller graph (only content nodes are
+    // merged). Either the node itself is a content node or we let the node
+    // point to one.
+    conGraph->escapeContentsOf(Node);
   }
 
   /// Gets or creates FunctionEffects for \p F.
@@ -902,6 +914,15 @@ class EscapeAnalysis : public BottomUpIPAnalysis {
     return FInfo;
   }
 
+  /// Get or create the node representing the memory pointed to by \p
+  /// addrVal. If \p addrVal is an address, then return the content node for the
+  /// variable's memory. Otherwise, \p addrVal may contain a reference, so
+  /// return the content node for the referenced heap object.
+  ///
+  /// Note that \p addrVal cannot be an address within a heap object, such as
+  /// an address from ref_element_addr or project_box.
+  CGNode *getValueContent(ConnectionGraph *conGraph, SILValue addrVal);
+
   /// Build a connection graph for reach callee from the callee list.
   bool buildConnectionGraphForCallees(SILInstruction *Caller,
                                       CalleeList Callees,