Merge pull request swiftlang#35671 from atrick/ossa-borrow-utils

Centralize and document low-level OSSA 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,21 +460,24 @@ 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 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};
+  /// If value is a borrow introducer, create a valid BorrowedValue.
+  explicit BorrowedValue(SILValue value) {
+    kind = BorrowedValueKind::get(value);
+    if (kind)
+      this->value = value;
   }
 
   operator bool() const { return kind != BorrowedValueKind::Invalid && value; }
@@ -430,14 +495,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 +518,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()); }
@@ -492,12 +560,6 @@ struct BorrowedValue {
   SILValue operator->() const { return value; }
   SILValue operator*() { return value; }
   SILValue operator*() const { return value; }
-
-private:
-  /// Internal constructor for failable static constructor. Please do not expand
-  /// its usage since it assumes the code passed in is well formed.
-  BorrowedValue(SILValue value, BorrowedValueKind kind)
-      : value(value), kind(kind) {}
 };
 
 llvm::raw_ostream &operator<<(llvm::raw_ostream &os,
@@ -632,14 +694,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;
   }