OwnershipUtils review feedback: Comments and examples.

Author: atrick

SwiftCompilerSources/Sources/Optimizer/Utilities/BorrowUtils.swift

@@ -9,6 +9,126 @@
 // See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
 //
 //===----------------------------------------------------------------------===//
+//
+// Utilities that model Ownership SSA (OSSA) borrow scopes.
+//
+// A borrowing instruction borrows one or more operands over a new
+// borrow scope, up to its scope-ending uses. This is typically
+// checked during a def-use walk.
+//
+//   %val = some owned value
+//   %store = store_borrow %val to %addr // borrowing instruction
+//   ...                                 // borrow scope
+//   end_borrow %store                   // scope-ending use
+//
+// A begin-borrow value introduces a guaranteed OSSA lifetime. It
+// begins a new borrow scope that ends at its scope-ending uses. A
+// begin-borrow value may be defined by a borrowing instruction:
+//
+//   %begin = begin_borrow %val          // %begin borrows %val
+//   ...                                 // borrow scope
+//   end_borrow %begin                   // scope-ending use
+//
+// Other begin-borrow cases, however, like block arguments and
+// `load_borrow`, are not borrowing instructions. Begin-borrow values
+// are typically checked during a use-def walk. Here, walking up from
+// `%forward` finds `%begin` as the introducer of its guaranteed
+// lifetime:
+//
+//   %begin = load_borrow %addr          // begin-borrow value
+//   %forward = struct (%begin)          // forwards a guaranteed value
+//   ...
+//   end_borrow %begin                   // scope-ending use
+//  
+// Every guaranteed OSSA value has a set of borrow introducers, each
+// of which dominates the value and introduces a borrow scope that
+// encloses all forwarded uses of the guaranteed value.
+//
+//   %1 = begin_borrow %0                // borrow introducer for %3
+//   %2 = begin_borrow %1                // borrow introducer for %3
+//   %3 = struct (%1, %2)                // forwards two guaranteed values
+//   ... all forwarded uses of %3
+//   end_borrow %1                       // scope-ending use
+//   end_borrow %2                       // scope-ending use
+//
+// Inner borrow scopes may be nested in outer borrow scopes:
+//
+//   %1 = begin_borrow %0                // borrow introducer for %2
+//   %2 = begin_borrow %1                // borrow introducer for %3
+//   %3 = struct (%2)
+//   ... all forwarded uses of %3
+//   end_borrow %2                       // scope-ending use of %2
+//   end_borrow %1                       // scope-ending use of %1
+//
+// Walking up the nested OSSA lifetimes requires iteratively querying
+// "enclosing values" until either a guaranteed function argument or
+// owned value is reached. Like a borrow introducer, an enclosing
+// value dominates all values that it encloses.
+//
+//                                Borrow Introducer    Enclosing Value
+//                                ~~~~~~~~~~~~~~~~~    ~~~~~~~~~~~~~~~
+//   %0 = some owned value        invalid              none
+//   %1 = begin_borrow %0         %1                   %0
+//   %2 = begin_borrow %1         %2                   %1
+//   %3 = struct (%2)             %2                   %2
+//
+// The borrow introducer of a guaranteed phi is not directly
+// determined by a use-def walk because an introducer must dominate
+// all uses in its scope:
+//
+//                                Borrow Introducer    Enclosing Value
+//                                ~~~~~~~~~~~~~~~~~    ~~~~~~~~~~~~~~~
+//                                
+//     cond_br ..., bb1, bb2      
+//   bb1:                         
+//     %2 = begin_borrow %0       %2                   %0
+//     %3 = struct (%2)           %2                   %2
+//     br bb3(%2, %3)             
+//   bb2:                         
+//     %6 = begin_borrow %0       %6                   %0
+//     %7 = struct (%6)           %6                   %6
+//     br bb3(%6, %7)             
+//   bb3(%reborrow: @guaranteed,  %reborrow            %0
+//       %phi: @guaranteed):      %phi                 %reborrow
+//  
+// `%reborrow` is an outer-adjacent phi to `%phi` because it encloses
+// `%phi`. `%phi` is an inner-adjacent phi to `%reborrow` because its
+// uses keep `%reborrow` alive. An outer-adjacent phi is either an
+// owned value or a reborrow. An inner-adjacent phi is either a
+// reborrow or a guaranteed forwarding phi. Here is an example of an
+// owned outer-adjacent phi with an inner-adjacent reborrow:
+// 
+//                                Borrow Introducer    Enclosing Value
+//                                ~~~~~~~~~~~~~~~~~    ~~~~~~~~~~~~~~~
+//                                
+//     cond_br ..., bb1, bb2      
+//   bb1:                         
+//     %1 = owned value           
+//     %2 = begin_borrow %0       %2                   %1
+//     br bb3(%1, %2)             
+//   bb2:                         
+//     %5 = owned value           
+//     %6 = begin_borrow %5       %6                   %5
+//     br bb3(%5, %6)             
+//   bb3(%phi: @owned,            invalid              %0
+//       %reborrow: @guaranteed): %reborrow            %phi
+//  
+// In OSSA, each owned value defines a separate lifetime. It is
+// consumed on all paths by a direct use. Owned lifetimes can,
+// however, be nested within a borrow scope. In this case, finding the
+// scope-ending uses requires traversing owned forwarding
+// instructions:
+//
+//   %1 = partial_apply %f(%0) // borrowing instruction borrows %0 and produces
+//                             // an owned closure value.
+//   %2 = struct (%1)          // end owned lifetime %1, begin owned lifetime %2
+//   destroy_value %2          // end owned lifetime %2, scope-ending use of %1
+//
+//
+// TODO: These utilities should be integrated with OSSA SIL verification and
+// guaranteed to be compelete (produce known results for all legal SIL
+// patterns).
+// ===----------------------------------------------------------------------===//
 
 import SIL
 

SwiftCompilerSources/Sources/Optimizer/Utilities/OwnershipLiveness.swift

@@ -10,6 +10,8 @@
 //
 //===----------------------------------------------------------------------===//
 //
+// Utilities that specify ownership SSA (OSSA) lifetimes.
+//
 // TODO: Implement ExtendedLinearLiveness. This requires
 // MultiDefPrunedLiveness, which is not supported by InstructionRange.
 //
@@ -60,28 +62,29 @@ func computeLinearLiveness(for definingValue: Value, _ context: Context)
   return range
 }
 
-/// Indicate whether OwnershipUseVisitor is visiting a use of the
-/// outer OSSA lifetime or within an inner borrow scope (reborrow).
-enum IsInnerLifetime {
-case outerLifetime
-case innerLifetime
-}
-
 typealias InnerScopeHandler = (Value) -> WalkResult
 
 /// Compute liveness and return a range, which the caller must deinitialize.
 ///
-/// An OSSA lifetime begins with a single "defining" value, which
-/// must be owned, or must begin a borrow scope.
+/// An OSSA lifetime begins with a single "defining" value, which must
+/// be owned, or must begin a borrow scope. A complete OSSA lifetime
+/// has a linear lifetime, meaning that it has a lifetime-ending use
+/// on all paths. Interior liveness computes liveness without assuming
+/// the lifetime is complete. To do this, it must find all "use
+/// points" and prove that the defining value is never propagated
+/// beyond those points. This is used to initially complete OSSA
+/// lifetimes and fix them after transformations that's don't preserve
+/// OSSA.
 ///
-/// - Liveness does not extend beyond lifetime-ending operations
-/// (a.k.a. affine lifetimes).
+/// Invariants:
 ///
 /// - The definition dominates all use points.
 ///
-/// - Does not assume the current lifetime is complete, but does
-/// assume any inner scopes are complete. Use `innerScopeHandler` to
-/// complete them or bail-out.
+/// - Liveness does not extend beyond lifetime-ending operations
+/// (a.k.a. affine lifetimes).
+///
+/// - All inner scopes are complete. (Use `innerScopeHandler` to
+/// complete them or bail-out).
 func computeInteriorLiveness(for definingValue: Value,
   _ context: FunctionPassContext,
   innerScopeHandler: InnerScopeHandler? = nil) -> InstructionRange {
@@ -115,7 +118,7 @@ func computeInteriorLiveness(for definingValue: Value,
   return range
 }
 
-/// Visit all interior uses of on OSSA lifetime.
+/// Visit all interior uses of an OSSA lifetime.
 ///
 /// - `definingValue` dominates all uses. Only dominated phis extend
 /// the lifetime. All other phis must have a lifetime-ending outer
@@ -132,14 +135,14 @@ func computeInteriorLiveness(for definingValue: Value,
 /// begin_access) A `innerScopeHandler` callback may be used to
 /// complete inner scopes before updating liveness.
 ///
-/// InteriorUseVisitor can be used to complete (linearize) an OSSA
+/// InteriorUseWalker can be used to complete (linearize) an OSSA
 /// lifetime after transformation that invalidates OSSA.
 ///
 /// Example:
 ///
-///     %struct = struct ...
+///     %s = struct ...
 ///     %f = struct_extract %s     // defines a guaranteed value (%f)
-///     %b = begin_borrow %field
+///     %b = begin_borrow %f
 ///     %a = ref_element_addr %b
 ///     _  = address_to_pointer %a
 ///     end_borrow %b              // the only interior use of %f
@@ -631,17 +634,46 @@ extension AddressUseVisitor {
   }
 }
 
-/// Enumerate all special cases of ownership uses in a visitor
-/// API. This encourages anyone who needs to analyze ownership uses to
-/// think about all of the special cases, many of which result
-/// from phis of borrowed values. Relying on linear lifetimes, which
-/// results from running "lifetime completion", allows you to ignore
-/// those cases.
+/// For OwnershipUseVisitor API entry points that operate on a
+/// use, Isinnerlifetime indicates whether the value being used is
+/// defined by the "outer" OSSA lifetime or an inner borrow scope.
+///
+/// When the OwnershipUseVisitor is invoked on an outer value
+/// (visitUsesOfOuter(value:)), it visits all the uses of that value
+/// and also visits the lifetime-ending uses of any inner borrow
+/// scopes. This provides a complete set of liveness "use points":
+///
+///   %0 = begin_borrow %outerValue
+///   %1 = begin_borrow %0
+///   end_borrow %1        // inner "use point" of %0
+///   end_borrow %0        // outer use of %1
+///
+/// This becomes more complicated with reborrows and closures. The
+/// implementation can simply rely on IsInnerLifetime to know whether
+/// the value being used is part of the outer lifetimes vs. its inner
+/// lifetimes. This is important, for example, if the implementation
+/// wants to know if the use ends the lifetime of the outer value.
+///
+/// Visitor implementations treat inner and outer uses differently. It
+/// may, for example, assume that inner lifetimes are complete
+/// and therefore only care about the lifetime-ending uses.
+enum IsInnerLifetime {
+case outerLifetime
+case innerLifetime
+}
+
+/// Package operand ownership into a visitor API.
+///
+/// Code that relies on effect of a use on ownership of its value
+/// should conform to this visitor. This ensures correct handling for
+/// special cases involving borrow scopes and interior pointers.
 ///
-/// To visit a value's uses:
+/// `visitUsesOfOuter(value:)` is the main entry point.
 ///
-/// - visitUsesOfOuter(value:)
-/// - visitUsesOfInner(value:)
+/// `visitUsesOfInner(value:)` is called back for each inner borrow
+/// scope. The implementation may or may not decide to recurse through
+/// reborrows and nested borrow scopes, calling back to
+/// `visitUsesOfInner(value:)` as needed.
 ///
 /// Visitors need to implement:
 ///
@@ -652,14 +684,14 @@ extension AddressUseVisitor {
 ///
 /// This only visits the first level of uses. The implementation may
 /// transitively visit forwarding operations in its implementation of
-/// `visitForwarding(operand:_)` and `visitReborrow(operand:_)`,
-/// calling back to `visitUsesOfOuter(value:)` or
+/// `visitForwarding(operand:_)` and `visitReborrow(operand:_)`, which
+/// can recursively call back to `visitUsesOfOuter(value:)` or
 /// `visitUsesOfInner(value:)`.
 ///
-/// For uses that begin a borrow or access scope, this skips ahead to
-/// the end of the scope. To record incomplete or dead inner scopes
-/// (no scope-ending use on some path), the implementation must
-/// override handleInner(borrow:).
+/// For uses that begin a borrow or access scope, this correctly
+/// "skips ahead" to the end of the scope. To record incomplete or
+/// dead inner scopes (no scope-ending use on some path), the
+/// implementation must override `handleInner(borrow:)`.
 protocol OwnershipUseVisitor {
   var _context: Context { get }
 
@@ -698,30 +730,36 @@ protocol OwnershipUseVisitor {
   /// result and implement this as a fatalError.
   mutating func visitPointerEscape(use: Operand) -> WalkResult
 
-  /// Handle begin_borrow, load_borrow, store_borrow, begin_apply.
+  /// Handles any of:
   ///
-  /// Handle an inner adjacent phi where the original OSSA def is a
-  /// phi in the same block
+  /// - begin_borrow, load_borrow, store_borrow, begin_apply.
   ///
-  /// Handle a reborrow of an inner borrow scope or inner adjacent phi
+  /// - an inner adjacent phi (where the value currently being visited is an
+  /// outer adjacent phi in the same block).
+  ///
+  /// - a reborrow of an inner borrow scope or a reborrow of an inner
+  /// adjacent phi.
   ///
   /// If this returns .continueWalk, then visit(use:) will be called
-  /// on the scope ending operands.
+  /// on the scope-ending operands.
   ///
-  /// Allows the implementation to complete inner scopes before considering
-  /// their scope ending operations as uses of the outer scope.
+  /// Allows the implementation to complete an inner scope before
+  /// visiting its scope-ending operations as uses of the outer
+  /// scope. The implementation may add uses to the inner scope, but
+  /// it may not modify the use-list containing \p address or in any
+  /// outer scopes.
   mutating func handleInner(borrow: BeginBorrowValue) -> WalkResult
 
   /// Handle begin_access.
   ///
   /// If this returns .continueWalk, then visit(use:) will be called
   /// on the scope ending operands.
   ///
-  /// Allows the implementation to complete inner scopes before considering
-  /// their scope ending operations as uses of the outer scope.
-  ///
-  /// This may add uses to the inner scope, but it may not modify the use-list
-  /// containing \p address or in any outer scopes.
+  /// Allows the implementation to complete an inner scope before
+  /// visiting its scope-ending operations as uses of the outer
+  /// scope. The implementation may add uses to the inner scope, but
+  /// it may not modify the use-list containing \p address or in any
+  /// outer scopes.
   mutating func handleAccess(address: BeginAccessInst) -> WalkResult
 }