Centralize and document low-level OSSA utilities

...for handling borrow scopes:

- find[Extended]TransitiveGuaranteedUses

- BorrowingOperand::visit[Extended]ScopeEndingUses

- BorrowedValue BorrowingOperand::getBorrowIntroducingUserResult()

And document the logic.

Mostly NFC in this commit, but more RAUW cases should be correctly
handled now.

Particularly, ensure that we can cleanly handle all manner of
reborrows. This is necessary to ensure both CanonicalizeOSSA and
replace-all-uses higher-level utilities handle all cases.

This generalizes some of the logic in CanonicalizeOSSA so it can be
shared by other high-level OSSA utilities.

These utilities extend the fundamental BorrowingOperand and
BorrowedValue functionality that has been designed recently. It builds
on and replaces a mix of piece-meal functionality that was needed
during bootstrapping. These APIs are now consistent with the more
recently designed code. It should be obvious what they mean and how to
use them, should be very hard to use them incorrectly, and should be
as efficient as possible, since they're fundamental to other
higher-level utilities.

Most importantly, there were several very subtle correctness issues
that were not handled cleanly in a centralized way. There are now a
mix of higher-level utilities trying to use this underlying
functionality, but it was hard to tell if all those higher-level
utilities were covering all the subtle cases:

- checking for PointerEscapes everywhere we need to

- the differences between uses of borrow introducers and other
  guaranteed values

- handling the uses of nested borrow scopes

- transitively handling reborrows

- the difference between nested and top-level reborrows

- forwarding destructures (which can cause exponential explosion)

In short, I was fundamentally confused and getting things wrong before
designing these utilities.

Author: atrick

include/swift/SIL/OwnershipUtils.h

@@ -75,6 +75,66 @@ inline bool isForwardingConsume(SILValue value) {
   return canOpcodeForwardOwnedValues(value);
 }
 
+/// Find all "use points" of a guaranteed value within its enclosing borrow
+/// scope (without looking through reborrows). To find the use points of the
+/// extended borrow scope, after looking through reborrows, use
+/// findExtendedTransitiveGuaranteedUses() instead.
+///
+/// Accumulate results in \p usePoints. This avoids the need for separate
+/// worklist and result vectors. Existing vector elements are ignored.
+///
+/// "Use points" are the relevant points for determining lifetime. They are
+/// determined differently depending on each of these two cases:
+///
+/// 1. If \p guaranteedValue introduces a borrow scope (begin_borrow,
+/// load_borrow, or phi), then its only use points are the scope-ending uses,
+/// and this function returns true. This is, in fact, equivalent to calling
+/// BorrowedValue::visitLocalScopeEndingUses(). Any scope-ending uses that are
+/// reborrows are recorded as use points without following the reborrowed
+/// uses. The \p visitReborrow callback can be used to transitively process
+/// reborrows to discover the extended lifetime. Reborrows may be recursive, so
+/// this will require checking membership in a working set. Nested borrow scope
+/// are irrelevant to the parent scope's lifetime. They are not considered use
+/// points, and reborrows within those nested scope are not visited by \p
+/// visitReborrow.
+///
+/// 2. If \p guaranteedValue does not introduce a borrow scope (it is not a
+/// valid BorrowedValue), then its uses are discovered transitively by looking
+/// through forwarding operations. If any use is a PointerEscape, then this
+/// returns false without adding more uses--the guaranteed values lifetime is
+/// indeterminite. If a use introduces a nested borrow scope, it creates use
+/// points where the "extended" borrow scope ends. An extended borrow
+/// scope is found by looking through any reborrows that end the nested
+/// scope. Other uses within nested borrow scopes are ignored.
+bool findTransitiveGuaranteedUses(SILValue guaranteedValue,
+                                  SmallVectorImpl<Operand *> &usePoints,
+                                  function_ref<void(Operand *)> visitReborrow);
+
+/// Find all "use points" of guaranteed value across its extended borrow scope
+/// (looking through reborrows). The "use points" are the relevant points for
+/// determining lifetime.
+///
+/// Accumulate results in \p usePoints. This avoids the need for separate
+/// worklist and result vectors. Existing vector elements are ignored.
+///
+/// "Use points" are the relevant points for determining lifetime. They are
+/// determined differently depending on each of these two cases:
+///
+/// 1. If \p guaranteedValue introduces a borrow scope (begin_borrow,
+/// load_borrow, or phi), then its only use points are the extended scope-ending
+/// uses, and this function returns true. This is, in fact, equivalent to
+/// calling BorrowedValue::visitExtendedLocalScopeEndingUses().
+///
+/// 2. If \p guaranteedValue does not introduce a borrow scope (it is not a
+/// valid BorrowedValue), then its uses are discovered transitively by looking
+/// through forwarding operations. Only a BorrowedValue can have its lifetime
+/// extended by a reborrow; therefore, in this case, the algorithm is equivalent
+/// to findTransitiveGuaranteedUses(). See those comments for more detail.
+bool findExtendedTransitiveGuaranteedUses(
+  SILValue guaranteedValue,
+  SmallVectorImpl<Operand *> &usePoints);
+
+/// An operand that forwards ownership to one or more results.
 class ForwardingOperand {
   Operand *use = nullptr;
 
@@ -216,16 +276,21 @@ struct BorrowingOperand {
   /// over a region of code instead of just for a single instruction, visit
   /// those uses.
   ///
-  /// Returns true if all visitor invocations returns true. Exits early if a
-  /// visitor returns false.
+  /// Returns false and early exits if the visitor \p func returns false.
+  ///
+  /// For an instantaneous borrow, such as apply, this visits no uses. For
+  /// begin_apply it visits the end_apply uses. For borrow introducers, it
+  /// visits the end of the introduced borrow scope.
+  bool visitScopeEndingUses(function_ref<bool(Operand *)> func) const;
+
+  /// Visit the scope ending operands of the extended scope, after transitively
+  /// searching through reborrows. These uses might not be dominated by this
+  /// BorrowingOperand.
   ///
-  /// Example: An apply performs an instantaneous recursive borrow of a
-  /// guaranteed value but a begin_apply borrows the value over the entire
-  /// region of code corresponding to the coroutine.
+  /// Returns false and early exits if the visitor \p func returns false.
   ///
-  /// NOTE: Return false from func to stop iterating. Returns false if the
-  /// closure requested to stop early.
-  bool visitLocalEndScopeUses(function_ref<bool(Operand *)> func) const;
+  /// Note: this does not visit the intermediate reborrows.
+  bool visitExtendedScopeEndingUses(function_ref<bool(Operand *)> func) const;
 
   /// Returns true if this borrow scope operand consumes guaranteed
   /// values and produces a new scope afterwards.
@@ -247,10 +312,12 @@ struct BorrowingOperand {
     llvm_unreachable("Covered switch isn't covered?!");
   }
 
-  /// Is the result of this instruction also a borrow introducer?
+  /// Return true if the user instruction introduces a borrow scope? This is
+  /// true for both reborrows and nested borrows.
   ///
-  /// TODO: This needs a better name.
-  bool areAnyUserResultsBorrowIntroducers() const {
+  /// If true, the visitBorrowIntroducingUserResults() can be called to acquire
+  /// each BorrowedValue that introduces a new borrow scopes.
+  bool hasBorrowIntroducingUser() const {
     // TODO: Can we derive this by running a borrow introducer check ourselves?
     switch (kind) {
     case BorrowingOperandKind::Invalid:
@@ -267,24 +334,19 @@ struct BorrowingOperand {
     llvm_unreachable("Covered switch isn't covered?!");
   }
 
-  /// Visit all of the results of the operand's user instruction that are
-  /// consuming uses.
-  void visitUserResultConsumingUses(function_ref<void(Operand *)> visitor) const;
-
   /// Visit all of the "results" of the user of this operand that are borrow
   /// scope introducers for the specific scope that this borrow scope operand
   /// summarizes.
-  void
-  visitBorrowIntroducingUserResults(function_ref<void(BorrowedValue)> visitor) const;
-
-  /// Passes to visitor all of the consuming uses of this use's using
-  /// instruction.
   ///
-  /// This enables one to walk the def-use chain of guaranteed phis for a single
-  /// guaranteed scope by using a worklist and checking if any of the operands
-  /// are BorrowScopeOperands.
-  void visitConsumingUsesOfBorrowIntroducingUserResults(
-      function_ref<void(Operand *)> visitor) const;
+  /// Precondition: hasBorrowIntroducingUser() is true
+  ///
+  /// Returns false and early exits if \p visitor returns false.
+  bool visitBorrowIntroducingUserResults(
+      function_ref<bool(BorrowedValue)> visitor) const;
+
+  /// If this operand's user has a single borrowed value result return a
+  /// valid BorrowedValue instance.
+  BorrowedValue getBorrowIntroducingUserResult();
 
   /// Compute the implicit uses that this borrowing operand "injects" into the
   /// set of its operands uses.
@@ -398,22 +460,32 @@ struct InteriorPointerOperand;
 /// guaranteed results are borrow introducers. In practice this means that
 /// borrow introducers can not have guaranteed results that are not creating a
 /// new borrow scope. No such instructions exist today.
+///
+/// This provides utilities for visiting the end of the borrow scope introduced
+/// by this value. The scope ending uses are always dominated by this value and
+/// jointly post-dominate this value (see visitLocalScopeEndingUses()). The
+/// extended scope, including reborrows has end points that are not dominated by
+/// this value but still jointly post-dominate (see
+/// visitExtendedLocalScopeEndingUses()).
 struct BorrowedValue {
   SILValue value;
-  BorrowedValueKind kind;
+  BorrowedValueKind kind = BorrowedValueKind::Invalid;
 
-  BorrowedValue() : value(), kind(BorrowedValueKind::Invalid) {}
+  BorrowedValue() = default;
+
+  /// If \p value is a borrow introducer construct a valid BorrowedValue.
+  BorrowedValue(SILValue value) {
+    kind = BorrowedValueKind::get(value);
+    if (!kind)
+      return;
+    this->value = value;
+  }
 
   /// If value is a borrow introducer return it after doing some checks.
   ///
   /// This is the only way to construct a BorrowScopeIntroducingValue. We make
   /// the primary constructor private for this reason.
-  static BorrowedValue get(SILValue value) {
-    auto kind = BorrowedValueKind::get(value);
-    if (!kind)
-      return {nullptr, kind};
-    return {value, kind};
-  }
+  static BorrowedValue get(SILValue value) { return BorrowedValue(value); }
 
   operator bool() const { return kind != BorrowedValueKind::Invalid && value; }
 
@@ -430,14 +502,16 @@ struct BorrowedValue {
   /// instructions and pass them individually to visitor. Asserts if this is
   /// called with a scope that is not local.
   ///
+  /// Returns false and early exist if \p visitor returns false.
+  ///
   /// The intention is that this method can be used instead of
   /// BorrowScopeIntroducingValue::getLocalScopeEndingUses() to avoid
   /// introducing an intermediate array when one needs to transform the
   /// instructions before storing them.
   ///
   /// NOTE: To determine if a scope is a local scope, call
   /// BorrowScopeIntoducingValue::isLocalScope().
-  void visitLocalScopeEndingUses(function_ref<void(Operand *)> visitor) const;
+  bool visitLocalScopeEndingUses(function_ref<bool(Operand *)> visitor) const;
 
   bool isLocalScope() const { return kind.isLocalScope(); }
 
@@ -451,9 +525,10 @@ struct BorrowedValue {
                           DeadEndBlocks &deadEndBlocks) const;
 
   /// Given a local borrow scope introducer, visit all non-forwarding consuming
-  /// users. This means that this looks through guaranteed block arguments.
-  bool visitLocalScopeTransitiveEndingUses(
-      function_ref<void(Operand *)> visitor) const;
+  /// users. This means that this looks through guaranteed block arguments. \p
+  /// visitor is *not* called on Reborrows, only on final scope ending uses.
+  bool visitExtendedLocalScopeEndingUses(
+      function_ref<bool(Operand *)> visitor) const;
 
   void print(llvm::raw_ostream &os) const;
   SWIFT_DEBUG_DUMP { print(llvm::dbgs()); }
@@ -632,14 +707,15 @@ struct InteriorPointerOperand {
   /// Return the end scope of all borrow introducers of the parent value of this
   /// projection. Returns true if we were able to find all borrow introducing
   /// values.
-  bool visitBaseValueScopeEndingUses(function_ref<void(Operand *)> func) const {
+  bool visitBaseValueScopeEndingUses(function_ref<bool(Operand *)> func) const {
     SmallVector<BorrowedValue, 4> introducers;
     if (!getAllBorrowIntroducingValues(operand->get(), introducers))
       return false;
     for (const auto &introducer : introducers) {
       if (!introducer.isLocalScope())
         continue;
-      introducer.visitLocalScopeEndingUses(func);
+      if (!introducer.visitLocalScopeEndingUses(func))
+        return false;
     }
     return true;
   }