[sil-inst-opt] Add a new utility swift::replaceSingleUse.

Given an Operand *op, this API executes op->set(newSILValue) except that:

1. If the user of op is an end scope, this API no-opts. This API is only used in
   contexts where we are rewriting uses and are not interesting in end scope
   instructions since we are moving uses from one scope to another scope.

2. If the user of op is not an end scope, but is a lifetime ending use of
   op->get(), we insert a destroy_value|end_borrow as appropriate on op->get()
   to ensure op->get()'s lifetime is still ended. We assume that if
   op->getUser() is lifetime ending, that our caller has ensured that we can end
   newValue's lifetime.

Author: gottesmm

include/swift/SILOptimizer/Utils/InstOptUtils.h

@@ -673,6 +673,11 @@ SILBasicBlock::iterator replaceAllUsesAndErase(SingleValueInstruction *svi,
                                                SILValue newValue,
                                                InstModCallbacks &callbacks);
 
+/// Low level routine that replaces the current value of \p use with \p
+/// newValue.
+SILBasicBlock::iterator replaceSingleUse(Operand *use, SILValue newValue,
+                                         InstModCallbacks &callbacks);
+
 } // end namespace swift
 
 #endif

lib/SILOptimizer/Utils/InstOptUtils.cpp

@@ -1909,3 +1909,57 @@ swift::replaceAllUsesAndErase(SingleValueInstruction *svi, SILValue newValue,
 
   return nextii;
 }
+
+/// Given that we are going to replace use's underlying value, if the use is a
+/// lifetime ending use, insert an end scope scope use for the underlying value
+/// before we RAUW.
+static void cleanupUseOldValueBeforeRAUW(Operand *use, SILBuilder &builder,
+                                         SILLocation loc,
+                                         InstModCallbacks &callbacks) {
+  if (!use->isLifetimeEnding()) {
+    return;
+  }
+
+  switch (use->get().getOwnershipKind()) {
+  case OwnershipKind::Any:
+    llvm_unreachable("Invalid ownership for value");
+  case OwnershipKind::Owned: {
+    auto *dvi = builder.createDestroyValue(loc, use->get());
+    callbacks.createdNewInst(dvi);
+    return;
+  }
+  case OwnershipKind::Guaranteed: {
+    // Should only happen once we model destructures as true reborrows.
+    auto *ebi = builder.createEndBorrow(loc, use->get());
+    callbacks.createdNewInst(ebi);
+    return;
+  }
+  case OwnershipKind::None:
+    return;
+  case OwnershipKind::Unowned:
+    llvm_unreachable("Unowned object can never be consumed?!");
+  }
+  llvm_unreachable("Covered switch isn't covered");
+}
+
+SILBasicBlock::iterator swift::replaceSingleUse(Operand *use, SILValue newValue,
+                                                InstModCallbacks &callbacks) {
+  auto oldValue = use->get();
+  assert(oldValue != newValue && "Cannot RAUW a value with itself");
+
+  auto *user = use->getUser();
+  auto nextII = std::next(user->getIterator());
+
+  // If we have an end of scope marker, just return next. We are done.
+  if (isEndOfScopeMarker(user)) {
+    return nextII;
+  }
+
+  // Otherwise, first insert clean up our use's value if we need to and then set
+  // use to have a new value.
+  SILBuilderWithScope builder(user);
+  cleanupUseOldValueBeforeRAUW(use, builder, user->getLoc(), callbacks);
+  callbacks.setUseValue(use, newValue);
+
+  return nextII;
+}