Add OwnershipLiveness utilities

Encapsulate all the complexity of reborrows and guaranteed phi in 3
ownership liveness interfaces:

LinerLiveness, InteriorLiveness, and ExtendedLiveness.

Author: atrick

include/swift/SIL/OwnershipLiveness.h

@@ -0,0 +1,296 @@
+//===--- OwnershipLiveness.h ---------------------------------*- C++ -*----===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2023 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+///
+/// Terminology:
+///
+/// Linear lifetime: All paths through the value's definition to the
+/// function exit pass through exactly one lifetime-ending operation.
+///
+/// Complete OSSA: All owned values and borrow introducers have linear lifetime.
+///
+/// Borrow introducer: defines a guaranteed SILValue and an associated explicit
+/// borrow scope: begin_borrow, load_borrow, store_borrow, and phi.
+/// A phi only introduces a scope when `isGuaranteedForwarding` returns
+/// false. We refer to these as reborrows. Eventually, the phi will know whether
+/// it is a reborrow based on a flag or subclass. A guaranteed function argument
+/// conceptually introduces a borrow scope, but the scope is implicit in the
+/// function entry and return points.
+///
+/// Linear SSA liveness:
+///
+/// - Liveness for a single "defining" owned value or borrow introducing value
+///   assuming the value's lifetime is already linear.
+///
+/// - The definition dominates all use points (phis do not extend the lifetime)
+///
+/// - Only lifetime-ending operations generate liveness
+///
+/// - Oblivious to pointer escapes within the lifetime
+///
+///
+/// Interior SSA liveness:
+///
+/// - Liveness for a single "defining" value with any ownership.
+///
+/// - The definition dominates all use points (phis do not extend the lifetime)
+///
+/// - Does not assume the current lifetime is linear. Transitively follows
+///   guaranteed forwarding and address uses within the current scope.
+///
+/// - Liveness cannot extend beyond lifetime-ending operations
+///   (a.k.a. affine lifetimes).
+///
+/// - Assumes inner scopes *are* linear, including borrow and address scopes
+///   (e.g. begin_borrow, load_borrow, begin_apply, store_borrow, begin_access)
+///   A callback may be used to complete inner scopes before updating liveness.
+///   Rarely returns AddressUseKind::PointerEscape, because inner scopes hide
+///   pointer escapes.
+///
+/// - Insulates outer scopes from inner scope details. Maintains the
+///   invariant that inlining cannot pessimize optimization.
+///
+/// - Interior SSA liveness is used to complete (linearize) an OSSA lifetime
+///
+/// Interior liveness example:
+///
+///     %struct = struct ...
+///     %f = struct_extract %s     // defines a guaranteed value
+///     %b = begin_borrow %field
+///     %a = ref_element_addr %b
+///     _  = address_to_pointer %a
+///     end_borrow %b              // the only interior use of %f
+///
+/// When computing interior liveness for %f, %b is an inner scope. Because inner
+/// scopes are complete, the only relevant use is end_borrow %b. Despite the
+/// address_to_pointer instruction, %f does not escape any dependent address.
+///
+/// Transitive SSA liveness
+///
+/// - Liveness for a single "defining" value with any ownership.
+///
+/// - The definition dominates all use points (phis do not extend the lifetime)
+///
+/// - Does not assume that any lifetimes are linear. Transitively follows uses
+///   within inner scopes, recursively through nested scopes, including
+///   forwarding operations and address uses.
+///
+/// - Much more likely to return AddressUseKind::PointerEscape
+///
+/// - ** Transitive liveness is no longer needed with complete OSSA lifetimes **
+///
+/// Transitive liveness example:
+///
+///     %struct = struct ...
+///     %f = struct_extract %s     // defines a guaranteed value
+///     %b = begin_borrow %field
+///     %a = ref_element_addr %b
+///     _  = address_to_pointer %a // a transitive use of %f escapes
+///
+/// When computing transitive liveness for %f, %b is an inner scope. Liveness
+/// does not assume that an end_borrow exists. Instead it transitively considers
+/// all uses of %b. As a result, %f escapes.
+///
+/// Extended liveness
+///
+/// - Liveness of a single "defining" value extended beyond its lifetime-ending
+///   operations.
+///
+/// - May refer to copy-extension, reborrow-extension, or extension over
+///   barriers such as access markers.
+///
+/// - For reborrow-extension, the definition no longer dominates the use
+///   points. MultiDefPrunedLiveness must be used. Each extended reborrow is
+///   added as a new definition.
+///
+///
+/// Extended linear liveness
+///
+/// - Only considers lifetime-ending operations. Assumes the definition already
+///   has a linear lifetime and all copy-extended or reborrow-extended lifetimes
+///   are also linear.
+///
+///
+/// Extended interior liveness
+///
+/// - Like interior SSA liveness, does not assume the current lifetime is
+///   linear. Transitively follows guaranteed forwarding and address uses within
+///   the current scope. Assumes inner scopes *are* linear.
+///
+/// - Interior copy-extension is used to canonicalize an OSSA lifetime
+///
+/// - Interior reborrow-extension is used to check borrow scopes relative to
+///   their inner uses and outer lifetime.
+///
+//===----------------------------------------------------------------------===//
+///
+/// Completing an OSSA lifetime may require phi creation whenever a reborrow is
+/// not dominated by the OSSA definition. The new phi's lifetime will then be
+/// extended over any of its inner adjacent phis.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef SWIFT_SIL_OWNERSHIPLIVENESS_H
+#define SWIFT_SIL_OWNERSHIPLIVENESS_H
+
+#include "swift/Basic/Debug.h"
+#include "swift/Basic/LLVM.h"
+#include "swift/SIL/PrunedLiveness.h"
+#include "swift/SIL/OwnershipUseVisitor.h"
+#include "swift/SIL/SILArgument.h"
+#include "swift/SIL/SILBasicBlock.h"
+#include "swift/SIL/SILInstruction.h"
+#include "swift/SIL/SILValue.h"
+#include "llvm/ADT/SmallVector.h"
+
+namespace swift {
+
+/// Analyze SSA liveness of values that introduce an OSSA live range:
+///
+/// 1. Owned non-phi values
+/// 2. Owned phi values
+/// 3. Borrow scope introducers: begin_borrow/load_borrow
+/// 4. Reborrows: guaranteed phis transitively defined by at least one borrow
+///    scope introducer.
+///
+/// Used for OSSA lifetime completion.
+class OSSALiveness {
+protected:
+  SILValue ownershipDef;
+
+  // MARK: Results.
+
+  SmallVector<SILBasicBlock *, 8> discoveredBlocks;
+  SSAPrunedLiveness liveness;
+
+  OSSALiveness(const OSSALiveness &) = delete;
+  OSSALiveness &operator=(const OSSALiveness &) = delete;
+
+public:
+  OSSALiveness(SILValue def): ownershipDef(def), liveness(&discoveredBlocks) {}
+
+  const SSAPrunedLiveness &getLiveness() const { return liveness; }
+
+  ArrayRef<SILBasicBlock *> getDiscoveredBlocks() const {
+    return discoveredBlocks;
+  }
+
+  void print(llvm::raw_ostream &OS) const;
+  void dump() const;
+};
+
+// Internal implementation
+struct LinearLivenessVisitor;
+
+/// Compute ownershipDef's lifetime based on it's lifetime-ending uses, assuming
+/// it is already complete/linear. ownershipDef must be either an owned value or
+/// a local borrow scope introduced (begin_borrow, load_borrow, or
+/// store_borrow).
+///
+/// This is the simplest OSSA liveness analysis, but is not appropriate for
+/// fixing OSSA lifetimes after transformation and cannot tell you whether
+/// pointer escapes occur.
+class LinearLiveness : public OSSALiveness {
+  friend LinearLivenessVisitor;
+
+public:
+  LinearLiveness(SILValue def);
+
+  void compute();
+};
+
+// Internal implementation
+struct InteriorLivenessVisitor;
+
+/// Compute ownershipDef's lifetime based on all its uses (except those
+/// already enclosed by inner scopes). Returns AddressUseKind::PointerEscape
+/// if a pointer to ownershipDef escapes (and is not already enclosed by an
+/// inner scope).
+class InteriorLiveness : public OSSALiveness {
+  friend InteriorLivenessVisitor;
+
+  // Handle inner scopes. Called for inner reborrows, inner adjacent reborrows,
+  // and address scopes.
+  //
+  // This may add uses to the inner scope, but it may not modify a use-list
+  // in any outer scopes.
+  using InnerScopeHandlerRef = llvm::function_ref<void(SILValue)>;
+
+public:
+  // Summarize address uses
+  AddressUseKind addressUseKind = AddressUseKind::Unknown;
+
+  // Record any guaranteed phi uses that are not already enclosed by an outer
+  // adjacent phi.
+  SmallVector<SILValue, 8> unenclosedPhis;
+
+public:
+  InteriorLiveness(SILValue def): OSSALiveness(def) {}
+
+  void compute(const DominanceInfo *domInfo,
+               InnerScopeHandlerRef handleInnerScope = InnerScopeHandlerRef());
+
+  AddressUseKind getAddressUseKind() const { return addressUseKind; }
+
+  ArrayRef<SILValue> getUnenclosedPhis() const { return unenclosedPhis; }
+
+  void print(llvm::raw_ostream &OS) const;
+  void dump() const;
+};
+
+// Internal implementation
+struct ExtendedLivenessVisitor;
+
+/// Analyze liveness of values that introduce an OSSA live range. This computes
+/// the phi-extended live range for these four categories of live range
+/// introducing values:
+///
+/// 1. Owned non-phi values
+/// 2. Owned phi values
+/// 3. Borrow scope introducers: begin_borrow/load_borrow
+/// 4. Reborrows: guaranteed phis that end their incoming borrow scopes and
+///    begin a new borrow scope
+class ExtendedLiveness {
+  friend ExtendedLivenessVisitor;
+
+  SILValue ownershipDef;
+
+  // MARK: Results.
+
+  // Because of reborrows, the ssa def may not dominate all
+  // uses. Consider the reborrows to be separate defs.
+  SmallVector<SILBasicBlock *, 8> discoveredBlocks;
+  MultiDefPrunedLiveness liveness;
+
+  ExtendedLiveness(const ExtendedLiveness &) = delete;
+  ExtendedLiveness &operator=(const ExtendedLiveness &) = delete;
+
+public:
+  ExtendedLiveness(SILValue def);
+
+  void compute();
+
+  /// The array of defs. The first element is ownershipDef. The remaining
+  /// elements are outer reborrows discovered during computation.
+  ///
+  /// TODO: These are always SILValues. Convert the iterator.
+  NodeSetVector::iterator defBegin() const { return liveness.defBegin(); }
+  NodeSetVector::iterator defEnd() const { return liveness.defBegin(); }
+
+  const MultiDefPrunedLiveness &getLiveness() const { return liveness; }
+
+  void print(llvm::raw_ostream &OS) const;
+  void dump() const;
+};
+
+} // namespace swift
+
+#endif