[sil] Define ValueBase::getNextInstruction().

Sometimes when you are working with SILValues, you need a "next" insertion
point. This creates a problem with the SILValue API since even though one can
get an instruction or an insertion point for a value, to find the appropriate
next instruction one needs to pierce through the API and see if one has a
SILArgument or SILInstruction breaking the whole point of abstraction. The
specific problem here is that a SILArgument's "next instruction" is the first
element of the block (that is ValueBase::getDefiningInsertionPoint()) and
SILInstruction's "next instruction" is
std::next(ValueBase::getDefiningInsertionPoint()). This new
API (ValueBase::getNextInstruction()) handles this case for the compiler writer
and eliminates unnecessary code contortions.

I also did a little cleanup where I moved a doxygen comment from a near by a
const_casting trampoline method to the method that the trampoline called (see
getDefiningInsertionPoint()).

Author: gottesmm

include/swift/SIL/SILValue.h

@@ -468,11 +468,46 @@ class ValueBase : public SILNode, public SILAllocated<ValueBase> {
   /// For instruction results, this returns getDefiningInstruction(). For
   /// arguments, this returns SILBasicBlock::begin() for the argument's parent
   /// block. Returns nullptr for SILUndef.
+  SILInstruction *getDefiningInsertionPoint();
+
+  // Const version of \see getDefiningInsertionPoint.
   const SILInstruction *getDefiningInsertionPoint() const {
     return const_cast<ValueBase *>(this)->getDefiningInsertionPoint();
   }
 
-  SILInstruction *getDefiningInsertionPoint();
+  /// Return the next SIL instruction to execute /after/ this value is
+  /// available.
+  ///
+  /// Operationally this means that:
+  ///
+  /// * For SILArguments, this returns the first instruction in the block. This
+  ///   is the main divergence from getDefiningInsertionPoint (see discussion
+  ///   below).
+  ///
+  /// * For SILInstructions, this returns std::next.
+  ///
+  /// * For SILUndef, this returns nullptr.
+  ///
+  /// DISCUSSION: The reason that this exists is that when one wants a "next"
+  /// instruction pointer, one often times wants to write:
+  ///
+  ///   if (auto *insertPt = value->getDefiningInsertionPoint())
+  ///     return std::next(insertPt);
+  ///
+  /// This is incorrect for SILArguments since after processing a SILArgument,
+  /// we need to process the actual first instruction in the block. With this
+  /// API, one can simply do:
+  ///
+  ///   if (auto *inst = value->getNextInstruction())
+  ///     return inst;
+  ///
+  /// And get the correct answer every time.
+  SILInstruction *getNextInstruction();
+
+  // Const version of \see getDefiningInsertionPoint.
+  const SILInstruction *getNextInstruction() const {
+    return const_cast<ValueBase *>(this)->getNextInstruction();
+  }
 
   struct DefiningInstructionResult {
     SILInstruction *Instruction;

lib/SIL/IR/SILValue.cpp

@@ -81,6 +81,14 @@ SILInstruction *ValueBase::getDefiningInsertionPoint() {
   return nullptr;
 }
 
+SILInstruction *ValueBase::getNextInstruction() {
+  if (auto *inst = getDefiningInstruction())
+    return std::next(inst);
+  if (auto *arg = dyn_cast<SILArgument>(this))
+    return &*arg->getParentBlock()->begin();
+  return nullptr;
+}
+
 Optional<ValueBase::DefiningInstructionResult>
 ValueBase::getDefiningInstructionResult() {
   if (auto *inst = dyn_cast<SingleValueInstruction>(this))