Introduce IRInstruction

In order to unify the many structures we have that each represent instruction values, introduce the IRInstruction protocol.  LLVMValueRef now unconditionally conforms to IRInstruction to facilitate dynamic casts.  Note that this is strictly not correct.  In particular, constant folding means the result of a lot of IRBuilder calls wind up as just plain values.  Therefore, the return types for IRBuilder functions has only been refined in as many places where we can guarantee constant-folding will always produce an instruction or instruction sequence.

Ultimately, this protocol greases the wheels for a more robust AttachedMetadata API for which we need new shims.

Author: CodaFi

Sources/LLVM/AttachedMetadata.swift

@@ -52,7 +52,7 @@ extension IRGlobal {
   }
 }
 
-extension Instruction {
+extension IRInstruction {
   /// Retrieves all metadata entries attached to this instruction.
   public var metadata: AttachedMetadata {
     var count = 0

Sources/LLVM/BasicBlock.swift

@@ -61,13 +61,13 @@ public struct BasicBlock: IRValue {
   }
 
   /// Returns the first instruction in the basic block, if it exists.
-  public var firstInstruction: Instruction? {
+  public var firstInstruction: IRInstruction? {
     guard let val = LLVMGetFirstInstruction(llvm) else { return nil }
     return Instruction(llvm: val)
   }
 
   /// Returns the first instruction in the basic block, if it exists.
-  public var lastInstruction: Instruction? {
+  public var lastInstruction: IRInstruction? {
     guard let val = LLVMGetLastInstruction(llvm) else { return nil }
     return Instruction(llvm: val)
   }
@@ -98,10 +98,10 @@ public struct BasicBlock: IRValue {
   }
 
   /// Returns a sequence of the Instructions that make up this basic block.
-  public var instructions: AnySequence<Instruction> {
+  public var instructions: AnySequence<IRInstruction> {
     var current = firstInstruction
-    return AnySequence<Instruction> {
-      return AnyIterator<Instruction> {
+    return AnySequence<IRInstruction> {
+      return AnyIterator<IRInstruction> {
         defer { current = current?.next() }
         return current
       }

Sources/LLVM/Call.swift

@@ -3,7 +3,7 @@ import cllvm
 #endif
 
 /// Represents a simple function call.
-public struct Call: IRValue {
+public struct Call: IRInstruction {
   let llvm: LLVMValueRef
 
   /// Retrieves the underlying LLVM value object.
@@ -43,7 +43,7 @@ public struct Call: IRValue {
 }
 
 /// Represents a function call that may transfer control to an exception handler.
-public struct Invoke: IRValue {
+public struct Invoke: IRInstruction {
   let llvm: LLVMValueRef
 
   /// Retrieves the underlying LLVM value object.

Sources/LLVM/DIBuilder.swift

@@ -65,7 +65,7 @@ extension DIBuilder {
   ///   - location: The location of the variable in source.
   public func buildDeclare(
     of variable: IRValue,
-    before: Instruction,
+    before: IRInstruction,
     metadata: LocalVariableMetadata,
     expr: ExpressionMetadata,
     location: DebugLocation
@@ -133,7 +133,7 @@ extension DIBuilder {
   public func buildDbgValue(
     of value: IRValue,
     to metadata: LocalVariableMetadata,
-    before: Instruction,
+    before: IRInstruction,
     expr: ExpressionMetadata,
     location: DebugLocation
   ) {

Sources/LLVM/IRBuilder.swift

@@ -556,7 +556,7 @@ extension IRBuilder {
   /// - parameter name: The name for the newly inserted instruction.
   ///
   /// - returns: A value representing the value selected for by the condition.
-  public func buildSelect(_ cond: IRValue, then: IRValue, else: IRValue, name: String = "") -> IRValue {
+  public func buildSelect(_ cond: IRValue, then: IRValue, else: IRValue, name: String = "") -> IRInstruction {
     if let ty = cond.type as? IntType {
       precondition(ty.width == 1, "Switch statement condition must have bitwidth of 1, instead has bitwidth of \(ty.width)")
       return LLVMBuildSelect(llvm, cond.asLLVM(), then.asLLVM(), `else`.asLLVM(), name)
@@ -644,7 +644,7 @@ extension IRBuilder {
   ///
   /// - returns: A value representing `void`.
   @discardableResult
-  public func buildBr(_ block: BasicBlock) -> IRValue {
+  public func buildBr(_ block: BasicBlock) -> IRInstruction {
     return LLVMBuildBr(llvm, block.llvm)
   }
 
@@ -665,7 +665,7 @@ extension IRBuilder {
   ///
   /// - returns: A value representing `void`.
   @discardableResult
-  public func buildCondBr(condition: IRValue, then: BasicBlock, `else`: BasicBlock) -> IRValue {
+  public func buildCondBr(condition: IRValue, then: BasicBlock, `else`: BasicBlock) -> IRInstruction {
     return LLVMBuildCondBr(llvm, condition.asLLVM(), then.asLLVM(), `else`.asLLVM())
   }
 
@@ -686,7 +686,7 @@ extension IRBuilder {
   ///
   /// - returns: An IRValue representing `void`.
   @discardableResult
-  public func buildIndirectBr(address: BasicBlock.Address, destinations: [BasicBlock]) -> IRValue {
+  public func buildIndirectBr(address: BasicBlock.Address, destinations: [BasicBlock]) -> IRInstruction {
     guard let ret = LLVMBuildIndirectBr(llvm, address.asLLVM(), UInt32(destinations.count)) else {
       fatalError("Unable to build indirect branch to address \(address)")
     }
@@ -710,7 +710,7 @@ extension IRBuilder {
   ///
   /// - returns: A value representing `void`.
   @discardableResult
-  public func buildRet(_ val: IRValue) -> IRValue {
+  public func buildRet(_ val: IRValue) -> IRInstruction {
     return LLVMBuildRet(llvm, val.asLLVM())
   }
 
@@ -725,7 +725,7 @@ extension IRBuilder {
   ///
   /// - returns: A value representing `void`.
   @discardableResult
-  public func buildRetVoid() -> IRValue {
+  public func buildRetVoid() -> IRInstruction {
     return LLVMBuildRetVoid(llvm)
   }
 
@@ -738,18 +738,19 @@ extension IRBuilder {
   ///
   /// - returns: A value representing `void`.
   @discardableResult
-  public func buildUnreachable() -> IRValue {
+  public func buildUnreachable() -> IRInstruction {
     return LLVMBuildUnreachable(llvm)
   }
 
   /// Build a return from the current function back to the calling function with
   /// the given array of values as members of an aggregate.
   ///
-  /// - parameter values: The values to insert as members of the returned aggregate.
+  /// - parameter values: The values to insert as members of the returned
+  ///   aggregate.
   ///
   /// - returns: A value representing `void`.
   @discardableResult
-  public func buildRetAggregate(of values: [IRValue]) -> IRValue {
+  public func buildRetAggregate(of values: [IRValue]) -> IRInstruction {
     var values = values.map { $0.asLLVM() as Optional }
     return values.withUnsafeMutableBufferPointer { buf in
       return LLVMBuildAggregateRet(llvm, buf.baseAddress!, UInt32(buf.count))
@@ -842,10 +843,10 @@ extension IRBuilder {
   ///
   /// - returns: A value of the given type representing the result of matching
   ///   a clause during unwinding.
-  public func buildLandingPad(returning type: IRType, personalityFn: Function? = nil, clauses: [LandingPadClause], cleanup: Bool = false, name: String = "") -> IRValue {
+  public func buildLandingPad(returning type: IRType, personalityFn: Function? = nil, clauses: [LandingPadClause], cleanup: Bool = false, name: String = "") -> IRInstruction {
     precondition(cleanup || !clauses.isEmpty, "Landing pad must be created with clauses or as cleanup")
 
-    let lp : IRValue = LLVMBuildLandingPad(llvm, type.asLLVM(), personalityFn?.asLLVM(), UInt32(clauses.count), name)
+    let lp: IRInstruction = LLVMBuildLandingPad(llvm, type.asLLVM(), personalityFn?.asLLVM(), UInt32(clauses.count), name)
     for clause in clauses {
       LLVMAddClause(lp.asLLVM(), clause.asLLVM())
     }
@@ -911,7 +912,7 @@ extension IRBuilder {
   ///
   /// - returns: A value representing `void`.
   public func buildAlloca(type: IRType, count: IRValue? = nil,
-                          alignment: Alignment = .zero, name: String = "") -> IRValue {
+                          alignment: Alignment = .zero, name: String = "") -> IRInstruction {
     let allocaInst: LLVMValueRef
     if let count = count {
       allocaInst = LLVMBuildArrayAlloca(llvm, type.asLLVM(), count.asLLVM(), name)
@@ -934,7 +935,7 @@ extension IRBuilder {
   ///
   /// - returns: A value representing `void`.
   @discardableResult
-  public func buildStore(_ val: IRValue, to ptr: IRValue, ordering: AtomicOrdering = .notAtomic, volatile: Bool = false, alignment: Alignment = .zero) -> IRValue {
+  public func buildStore(_ val: IRValue, to ptr: IRValue, ordering: AtomicOrdering = .notAtomic, volatile: Bool = false, alignment: Alignment = .zero) -> IRInstruction {
     let storeInst = LLVMBuildStore(llvm, val.asLLVM(), ptr.asLLVM())!
     LLVMSetOrdering(storeInst, ordering.llvm)
     LLVMSetVolatile(storeInst, volatile.llvm)
@@ -954,7 +955,7 @@ extension IRBuilder {
   ///
   /// - returns: A value representing the result of a load from the given
   ///   pointer value.
-  public func buildLoad(_ ptr: IRValue, ordering: AtomicOrdering = .notAtomic, volatile: Bool = false, alignment: Alignment = .zero, name: String = "") -> IRValue {
+  public func buildLoad(_ ptr: IRValue, ordering: AtomicOrdering = .notAtomic, volatile: Bool = false, alignment: Alignment = .zero, name: String = "") -> IRInstruction {
     let loadInst = LLVMBuildLoad(llvm, ptr.asLLVM(), name)!
     LLVMSetOrdering(loadInst, ordering.llvm)
     LLVMSetVolatile(loadInst, volatile.llvm)
@@ -1258,6 +1259,31 @@ extension IRBuilder {
     }
   }
 
+  /// Build an expression that returns the difference between two pointer
+  /// values, dividing out the size of the pointed-to objects.
+  ///
+  /// This is intended to implement C-style pointer subtraction. As such, the 
+  /// pointers must be appropriately aligned for their element types and 
+  /// pointing into the same object.
+  ///
+  /// - parameter lhs: The first pointer (the minuend).
+  /// - parameter rhs: The second pointer (the subtrahend).
+  /// - parameter name: The name for the newly inserted instruction.
+  ///
+  /// - returns: A IRValue representing a 64-bit integer value of the difference
+  ///   of the two pointer values modulo the size of the pointed-to objects.
+  public func buildPointerDifference(_ lhs: IRValue, _ rhs: IRValue, name: String = "") -> IRValue {
+    precondition(
+      lhs.type is PointerType && rhs.type is PointerType,
+      "Cannot take pointer diff of \(lhs.type) and \(rhs.type)."
+    )
+    return LLVMBuildPtrDiff(llvm, lhs.asLLVM(), rhs.asLLVM(), name)
+  }
+}
+
+// MARK: Type Information
+
+extension IRBuilder {
   /// Build a constant expression that returns the alignment of the given type
   /// in bytes.
   ///
@@ -1279,27 +1305,6 @@ extension IRBuilder {
   public func buildSizeOf(_ val: IRType) -> IRValue {
     return LLVMSizeOf(val.asLLVM())
   }
-
-  /// Build an expression that returns the difference between two pointer
-  /// values, dividing out the size of the pointed-to objects.
-  ///
-  /// This is intended to implement C-style pointer subtraction. As such, the 
-  /// pointers must be appropriately aligned for their element types and 
-  /// pointing into the same object.
-  ///
-  /// - parameter lhs: The first pointer (the minuend).
-  /// - parameter rhs: The second pointer (the subtrahend).
-  /// - parameter name: The name for the newly inserted instruction.
-  ///
-  /// - returns: A IRValue representing a 64-bit integer value of the difference
-  ///   of the two pointer values modulo the size of the pointed-to objects.
-  public func buildPointerDifference(_ lhs: IRValue, _ rhs: IRValue, name: String = "") -> IRValue {
-    precondition(
-      lhs.type is PointerType && rhs.type is PointerType,
-      "Cannot take pointer diff of \(lhs.type) and \(rhs.type)."
-    )
-    return LLVMBuildPtrDiff(llvm, lhs.asLLVM(), rhs.asLLVM(), name)
-  }
 }
 
 // MARK: Atomic Instructions
@@ -1333,7 +1338,8 @@ extension IRBuilder {
   /// - parameter name: The name for the newly inserted instruction.
   ///
   /// - returns: A value representing `void`.
-  public func buildFence(ordering: AtomicOrdering, singleThreaded: Bool = false, name: String = "") -> IRValue {
+  @discardableResult
+  public func buildFence(ordering: AtomicOrdering, singleThreaded: Bool = false, name: String = "") -> IRInstruction {
     return LLVMBuildFence(llvm, ordering.llvm, singleThreaded.llvm, name)
   }
 
@@ -1424,7 +1430,7 @@ extension IRBuilder {
   ///                    C array.
   /// - parameter name: The intended name for the `malloc`'d value.
   public func buildMalloc(_ type: IRType, count: IRValue? = nil,
-                          name: String = "") -> IRValue {
+                          name: String = "") -> IRInstruction {
     if let count = count {
       return LLVMBuildArrayMalloc(llvm, type.asLLVM(), count.asLLVM(), name)
     } else {
@@ -1438,7 +1444,7 @@ extension IRBuilder {
   /// - parameter ptr: The pointer to `free`.
   /// - returns: The `free` instruction.
   @discardableResult
-  public func buildFree(_ ptr: IRValue) -> IRValue {
+  public func buildFree(_ ptr: IRValue) -> IRInstruction {
     return LLVMBuildFree(llvm, ptr.asLLVM())
   }
 }
@@ -1464,12 +1470,14 @@ extension IRBuilder {
   ///     relied upon to perform consistently.  For more information, see the
   ///     language reference's section on [Volatile Memory
   ///     Access](http://llvm.org/docs/LangRef.html#volatile-memory-accesses).
+  @discardableResult
   public func buildMemset(
     to dest: IRValue, of value: IRValue, length: IRValue,
     alignment: Alignment, volatile: Bool = false
-  ) {
-    let instruction = LLVMBuildMemSet(self.llvm, dest.asLLVM(), value.asLLVM(), length.asLLVM(), alignment.rawValue)
+  ) -> IRInstruction {
+    let instruction = LLVMBuildMemSet(self.llvm, dest.asLLVM(), value.asLLVM(), length.asLLVM(), alignment.rawValue)!
     LLVMSetVolatile(instruction, volatile.llvm)
+    return instruction
   }
 
   /// Builds a call to the `llvm.memcpy.*` family of intrinsics to copy a block
@@ -1495,13 +1503,15 @@ extension IRBuilder {
   ///     relied upon to perform consistently.  For more information, see the
   ///     language reference's section on [Volatile Memory
   ///     Access](http://llvm.org/docs/LangRef.html#volatile-memory-accesses).
+  @discardableResult
   public func buildMemCpy(
     to dest: IRValue, _ destAlign: Alignment,
     from src: IRValue, _ srcAlign: Alignment,
     length: IRValue, volatile: Bool = false
-  ) {
-    let instruction = LLVMBuildMemCpy(self.llvm, dest.asLLVM(), destAlign.rawValue, src.asLLVM(), srcAlign.rawValue, length.asLLVM())
+  ) -> IRInstruction {
+    let instruction = LLVMBuildMemCpy(self.llvm, dest.asLLVM(), destAlign.rawValue, src.asLLVM(), srcAlign.rawValue, length.asLLVM())!
     LLVMSetVolatile(instruction, volatile.llvm)
+    return instruction
   }
 
   /// Builds a call to the `llvm.memmove.*` family of intrinsics to move a
@@ -1527,13 +1537,15 @@ extension IRBuilder {
   ///     relied upon to perform consistently.  For more information, see the
   ///     language reference's section on [Volatile Memory
   ///     Access](http://llvm.org/docs/LangRef.html#volatile-memory-accesses).
+  @discardableResult
   public func buildMemMove(
     to dest: IRValue, _ destAlign: Alignment,
     from src: IRValue, _ srcAlign: Alignment,
     length: IRValue, volatile: Bool = false
-  ) {
-    let instruction = LLVMBuildMemMove(self.llvm, dest.asLLVM(), destAlign.rawValue, src.asLLVM(), srcAlign.rawValue, length.asLLVM())
+  ) -> IRInstruction {
+    let instruction = LLVMBuildMemMove(self.llvm, dest.asLLVM(), destAlign.rawValue, src.asLLVM(), srcAlign.rawValue, length.asLLVM())!
     LLVMSetVolatile(instruction, volatile.llvm)
+    return instruction
   }
 }
 

Sources/LLVM/IRValue.swift

@@ -20,6 +20,11 @@ public extension IRValue {
     return LLVMIsConstant(asLLVM()) != 0
   }
 
+  /// Returns whether this value is an instruction.
+  var isInstruction: Bool {
+    return LLVMIsAInstruction(asLLVM()) != nil
+  }
+
   /// Returns whether this value has been initialized with the special `undef`
   /// value.
   ///
@@ -151,6 +156,12 @@ extension LLVMValueRef: IRValue {
   }
 }
 
+// N.B. This conformance is strictly not correct, but LLVM-C chooses to muddy
+// the difference between LLVMValueRef and a number of what should be refined
+// types.  What matters is that we verify any returned `IRInstruction` values
+// are actually instructions.
+extension LLVMValueRef: IRInstruction {}
+
 extension Int: IRValue {
   /// Retrieves the underlying LLVM value object.
   public func asLLVM() -> LLVMValueRef {