Merge pull request rust-lang#254 from folkertdev/callable-value

Add CallableValue

Author: TheDan64

src/builder.rs

@@ -1,22 +1,21 @@
 //! A `Builder` enables you to build instructions.
 
-use either::{Either, Left, Right};
-use llvm_sys::core::{LLVMBuildAdd, LLVMBuildAlloca, LLVMBuildAnd, LLVMBuildArrayAlloca, LLVMBuildArrayMalloc, LLVMBuildAtomicRMW, LLVMBuildBr, LLVMBuildCall, LLVMBuildCast, LLVMBuildCondBr, LLVMBuildExtractValue, LLVMBuildFAdd, LLVMBuildFCmp, LLVMBuildFDiv, LLVMBuildFence, LLVMBuildFMul, LLVMBuildFNeg, LLVMBuildFree, LLVMBuildFSub, LLVMBuildGEP, LLVMBuildICmp, LLVMBuildInsertValue, LLVMBuildIsNotNull, LLVMBuildIsNull, LLVMBuildLoad, LLVMBuildMalloc, LLVMBuildMul, LLVMBuildNeg, LLVMBuildNot, LLVMBuildOr, LLVMBuildPhi, LLVMBuildPointerCast, LLVMBuildRet, LLVMBuildRetVoid, LLVMBuildStore, LLVMBuildSub, LLVMBuildUDiv, LLVMBuildUnreachable, LLVMBuildXor, LLVMDisposeBuilder, LLVMGetElementType, LLVMGetInsertBlock, LLVMGetReturnType, LLVMGetTypeKind, LLVMInsertIntoBuilder, LLVMPositionBuilderAtEnd, LLVMTypeOf, LLVMBuildExtractElement, LLVMBuildInsertElement, LLVMBuildIntToPtr, LLVMBuildPtrToInt, LLVMInsertIntoBuilderWithName, LLVMClearInsertionPosition, LLVMPositionBuilder, LLVMPositionBuilderBefore, LLVMBuildAggregateRet, LLVMBuildStructGEP, LLVMBuildInBoundsGEP, LLVMBuildPtrDiff, LLVMBuildNSWAdd, LLVMBuildNUWAdd, LLVMBuildNSWSub, LLVMBuildNUWSub, LLVMBuildNSWMul, LLVMBuildNUWMul, LLVMBuildSDiv, LLVMBuildSRem, LLVMBuildURem, LLVMBuildFRem, LLVMBuildNSWNeg, LLVMBuildNUWNeg, LLVMBuildFPToUI, LLVMBuildFPToSI, LLVMBuildSIToFP, LLVMBuildUIToFP, LLVMBuildFPTrunc, LLVMBuildFPExt, LLVMBuildIntCast, LLVMBuildFPCast, LLVMBuildSExtOrBitCast, LLVMBuildZExtOrBitCast, LLVMBuildTruncOrBitCast, LLVMBuildSwitch, LLVMAddCase, LLVMBuildShl, LLVMBuildAShr, LLVMBuildLShr, LLVMBuildGlobalString, LLVMBuildGlobalStringPtr, LLVMBuildExactSDiv, LLVMBuildTrunc, LLVMBuildSExt, LLVMBuildZExt, LLVMBuildSelect, LLVMBuildAddrSpaceCast, LLVMBuildBitCast, LLVMBuildShuffleVector, LLVMBuildVAArg, LLVMBuildIndirectBr, LLVMAddDestination};
+use llvm_sys::core::{LLVMBuildAdd, LLVMBuildAlloca, LLVMBuildAnd, LLVMBuildArrayAlloca, LLVMBuildArrayMalloc, LLVMBuildAtomicRMW, LLVMBuildBr, LLVMBuildCall, LLVMBuildCast, LLVMBuildCondBr, LLVMBuildExtractValue, LLVMBuildFAdd, LLVMBuildFCmp, LLVMBuildFDiv, LLVMBuildFence, LLVMBuildFMul, LLVMBuildFNeg, LLVMBuildFree, LLVMBuildFSub, LLVMBuildGEP, LLVMBuildICmp, LLVMBuildInsertValue, LLVMBuildIsNotNull, LLVMBuildIsNull, LLVMBuildLoad, LLVMBuildMalloc, LLVMBuildMul, LLVMBuildNeg, LLVMBuildNot, LLVMBuildOr, LLVMBuildPhi, LLVMBuildPointerCast, LLVMBuildRet, LLVMBuildRetVoid, LLVMBuildStore, LLVMBuildSub, LLVMBuildUDiv, LLVMBuildUnreachable, LLVMBuildXor, LLVMDisposeBuilder, LLVMGetInsertBlock, LLVMInsertIntoBuilder, LLVMPositionBuilderAtEnd, LLVMBuildExtractElement, LLVMBuildInsertElement, LLVMBuildIntToPtr, LLVMBuildPtrToInt, LLVMInsertIntoBuilderWithName, LLVMClearInsertionPosition, LLVMPositionBuilder, LLVMPositionBuilderBefore, LLVMBuildAggregateRet, LLVMBuildStructGEP, LLVMBuildInBoundsGEP, LLVMBuildPtrDiff, LLVMBuildNSWAdd, LLVMBuildNUWAdd, LLVMBuildNSWSub, LLVMBuildNUWSub, LLVMBuildNSWMul, LLVMBuildNUWMul, LLVMBuildSDiv, LLVMBuildSRem, LLVMBuildURem, LLVMBuildFRem, LLVMBuildNSWNeg, LLVMBuildNUWNeg, LLVMBuildFPToUI, LLVMBuildFPToSI, LLVMBuildSIToFP, LLVMBuildUIToFP, LLVMBuildFPTrunc, LLVMBuildFPExt, LLVMBuildIntCast, LLVMBuildFPCast, LLVMBuildSExtOrBitCast, LLVMBuildZExtOrBitCast, LLVMBuildTruncOrBitCast, LLVMBuildSwitch, LLVMAddCase, LLVMBuildShl, LLVMBuildAShr, LLVMBuildLShr, LLVMBuildGlobalString, LLVMBuildGlobalStringPtr, LLVMBuildExactSDiv, LLVMBuildTrunc, LLVMBuildSExt, LLVMBuildZExt, LLVMBuildSelect, LLVMBuildAddrSpaceCast, LLVMBuildBitCast, LLVMBuildShuffleVector, LLVMBuildVAArg, LLVMBuildIndirectBr, LLVMAddDestination};
 #[llvm_versions(3.9..=latest)]
 use llvm_sys::core::LLVMBuildAtomicCmpXchg;
 #[llvm_versions(8.0..=latest)]
 use llvm_sys::core::{LLVMBuildMemCpy, LLVMBuildMemMove};
 use llvm_sys::prelude::{LLVMBuilderRef, LLVMValueRef};
-use llvm_sys::{LLVMTypeKind};
 
 use crate::{AtomicOrdering, AtomicRMWBinOp, IntPredicate, FloatPredicate};
 use crate::basic_block::BasicBlock;
 use crate::support::to_c_str;
-use crate::values::{AggregateValue, AggregateValueEnum, AsValueRef, BasicValue, BasicValueEnum, PhiValue, FunctionValue, IntValue, PointerValue, VectorValue, InstructionValue, GlobalValue, IntMathValue, FloatMathValue, PointerMathValue, InstructionOpcode, CallSiteValue};
+use crate::values::{AggregateValue, AggregateValueEnum, AsValueRef, BasicValue, BasicValueEnum, PhiValue, IntValue, PointerValue, VectorValue, InstructionValue, GlobalValue, IntMathValue, FloatMathValue, PointerMathValue, InstructionOpcode, CallSiteValue};
 #[llvm_versions(7.0..=latest)]
 use crate::debug_info::DILocation;
 #[llvm_versions(3.9..=latest)]
 use crate::values::StructValue;
+use crate::values::CallableValue;
 use crate::types::{AsTypeRef, BasicType, IntMathType, FloatMathType, PointerType, PointerMathType};
 
 use std::marker::PhantomData;
@@ -107,9 +106,11 @@ impl<'ctx> Builder<'ctx> {
         }
     }
 
-    /// Builds a function call instruction. It can take either a `FunctionValue` or a `PointerValue`
-    /// which is a function pointer. It will panic if the `PointerValue` is not a function pointer.
-    /// This may be turned into a Result in the future, however.
+    /// Builds a function call instruction. 
+    /// [`FunctionValue`]s can be implicitly converted into a [`CallableValue`]. 
+    /// See [`CallableValue`] for details on calling a [`PointerValue`] that points to a function.
+    ///
+    /// [`FunctionValue`]: crate::values::FunctionValue
     ///
     /// # Example
     ///
@@ -137,32 +138,16 @@ impl<'ctx> Builder<'ctx> {
     /// ```
     pub fn build_call<F>(&self, function: F, args: &[BasicValueEnum<'ctx>], name: &str) -> CallSiteValue<'ctx>
     where
-        F: Into<FunctionOrPointerValue<'ctx>>,
+        F: Into<CallableValue<'ctx>>,
     {
-        let fn_val_ref = match function.into() {
-            Left(val) => val.as_value_ref(),
-            Right(val) => {
-                // If using a pointer value, we must validate it's a valid function ptr
-                let value_ref = val.as_value_ref();
-                let ty_kind = unsafe { LLVMGetTypeKind(LLVMGetElementType(LLVMTypeOf(value_ref))) };
-                let is_a_fn_ptr = match ty_kind {
-                    LLVMTypeKind::LLVMFunctionTypeKind => true,
-                    _ => false,
-                };
-
-                // REVIEW: We should probably turn this into a Result?
-                assert!(is_a_fn_ptr, "build_call called with a pointer which is not a function pointer");
-
-                value_ref
-            },
-        };
+        let callable_value = function.into();
+        let fn_val_ref = callable_value.as_value_ref();
 
         // LLVM gets upset when void return calls are named because they don't return anything
-        let name = unsafe {
-            match LLVMGetTypeKind(LLVMGetReturnType(LLVMGetElementType(LLVMTypeOf(fn_val_ref)))) {
-                LLVMTypeKind::LLVMVoidTypeKind => "",
-                _ => name,
-            }
+        let name = if callable_value.returns_void() {
+            ""
+        } else {
+            name
         };
 
         let c_string = to_c_str(name);
@@ -1892,17 +1877,3 @@ impl Drop for Builder<'_> {
         }
     }
 }
-
-type FunctionOrPointerValue<'ctx> = Either<FunctionValue<'ctx>, PointerValue<'ctx>>;
-
-impl<'ctx> Into<FunctionOrPointerValue<'ctx>> for FunctionValue<'ctx> {
-    fn into(self) -> FunctionOrPointerValue<'ctx> {
-        Left(self)
-    }
-}
-
-impl<'ctx> Into<FunctionOrPointerValue<'ctx>> for PointerValue<'ctx> {
-    fn into(self) -> FunctionOrPointerValue<'ctx> {
-        Right(self)
-    }
-}

src/context.rs

@@ -195,7 +195,9 @@ impl Context {
     ///
     /// # Example
     /// ```no_run
+    /// use std::convert::TryFrom;
     /// use inkwell::context::Context;
+    /// use inkwell::values::CallableValue;
     ///
     /// let context = Context::create();
     /// let module = context.create_module("my_module");
@@ -209,7 +211,8 @@ impl Context {
     /// let asm_fn = context.i64_type().fn_type(&[context.i64_type().into(), context.i64_type().into()], false);
     /// let asm = context.create_inline_asm(asm_fn, "syscall".to_string(), "=r,{rax},{rdi}".to_string(), true, false, None);
     /// let params = &[context.i64_type().const_int(60, false).into(), context.i64_type().const_int(1, false).into()];
-    /// builder.build_call(asm, params, "exit");
+    /// let callable_value = CallableValue::try_from(asm).unwrap();
+    /// builder.build_call(callable_value, params, "exit");
     /// builder.build_return(None);
     #[llvm_versions(7.0..=latest)]
     pub fn create_inline_asm(&self, ty: FunctionType, mut assembly: String, mut constraints: String, sideeffects: bool, alignstack: bool, dialect: Option<InlineAsmDialect>) -> PointerValue {
@@ -234,7 +237,9 @@ impl Context {
     ///
     /// # Example
     /// ```no_run
+    /// use std::convert::TryFrom;
     /// use inkwell::context::Context;
+    /// use inkwell::values::CallableValue;
     ///
     /// let context = Context::create();
     /// let module = context.create_module("my_module");
@@ -248,7 +253,8 @@ impl Context {
     /// let asm_fn = context.i64_type().fn_type(&[context.i64_type().into(), context.i64_type().into()], false);
     /// let asm = context.create_inline_asm(asm_fn, "syscall".to_string(), "=r,{rax},{rdi}".to_string(), true, false);
     /// let params = &[context.i64_type().const_int(60, false).into(), context.i64_type().const_int(1, false).into()];
-    /// builder.build_call(asm, params, "exit");
+    /// let callable_value = CallableValue::try_from(asm).unwrap();
+    /// builder.build_call(callable_value, params, "exit");
     /// builder.build_return(None);
     #[llvm_versions(3.6..7.0)]
     pub fn create_inline_asm(&self, ty: FunctionType, assembly: String, constraints: String, sideeffects: bool, alignstack: bool) -> PointerValue {

src/values/callable_value.rs

@@ -0,0 +1,123 @@
+use std::convert::TryFrom;
+use either::Either;
+
+use crate::values::AsValueRef;
+use crate::values::{FunctionValue, PointerValue, AnyValue};
+
+use llvm_sys::prelude::LLVMValueRef;
+use llvm_sys::core::{LLVMGetTypeKind, LLVMGetElementType, LLVMTypeOf, LLVMGetReturnType};
+use llvm_sys::LLVMTypeKind;
+
+/// A value that can be called with the [`build_call`] instruction.
+///
+/// In practice, the `F : Into<CallableValue<'ctx>>` bound of [`build_call`] means it is
+/// possible to pass a [`FunctionValue`] to [`build_call`] directly. It will be implicitly converted
+/// into a `CallableValue`.
+///
+/// [`build_call`]: crate::builder::Builder::build_call
+///
+/// ```no_run
+/// use inkwell::context::Context;
+///
+/// // A simple function which calls itself:
+/// let context = Context::create();
+/// let module = context.create_module("ret");
+/// let builder = context.create_builder();
+/// let i32_type = context.i32_type();
+/// let fn_type = i32_type.fn_type(&[i32_type.into()], false);
+/// let fn_value = module.add_function("ret", fn_type, None);
+/// let entry = context.append_basic_block(fn_value, "entry");
+/// let i32_arg = fn_value.get_first_param().unwrap();
+///
+/// builder.position_at_end(entry);
+///
+/// let ret_val = builder.build_call(fn_value, &[i32_arg], "call")
+///     .try_as_basic_value()
+///     .left()
+///     .unwrap();
+///
+/// builder.build_return(Some(&ret_val));
+/// ```
+///
+/// A [`PointerValue`] cannot be implicitly converted to a `CallableValue` because the pointer may
+/// point to a non-function value. Instead we can use [`TryFrom`] to handle this failure case explicitly.
+///
+/// ```no_run
+/// use std::convert::TryFrom;
+/// use inkwell::context::Context;
+/// use inkwell::values::CallableValue;
+///
+/// // A simple function which calls itself:
+/// let context = Context::create();
+/// let module = context.create_module("ret");
+/// let builder = context.create_builder();
+/// let i32_type = context.i32_type();
+/// let fn_type = i32_type.fn_type(&[i32_type.into()], false);
+/// let fn_value = module.add_function("ret", fn_type, None);
+/// let entry = context.append_basic_block(fn_value, "entry");
+/// let i32_arg = fn_value.get_first_param().unwrap();
+///
+/// builder.position_at_end(entry);
+///
+/// // take a pointer to the function value
+/// let fn_pointer_value = fn_value.as_global_value().as_pointer_value();
+///
+/// // convert that pointer value into a callable value
+/// // explicitly handling the failure case (here with `unwrap`)
+/// let callable_value = CallableValue::try_from(fn_pointer_value).unwrap();
+///
+/// let ret_val = builder.build_call(callable_value, &[i32_arg], "call")
+///     .try_as_basic_value()
+///     .left()
+///     .unwrap();
+///
+/// builder.build_return(Some(&ret_val));
+/// ```
+#[derive(Debug)]
+pub struct CallableValue<'ctx>(Either<FunctionValue<'ctx>, PointerValue<'ctx>>);
+
+impl<'ctx> AsValueRef for CallableValue<'ctx> {
+    fn as_value_ref(&self) -> LLVMValueRef {
+        use either::Either::*;
+
+        match self.0 {
+            Left(function) => function.as_value_ref(),
+            Right(pointer) => pointer.as_value_ref(),
+        }
+    }
+}
+
+impl<'ctx> AnyValue<'ctx> for CallableValue<'ctx> {}
+
+impl<'ctx> CallableValue<'ctx> {
+    pub(crate) fn returns_void(&self) -> bool {
+        let return_type = unsafe {
+            LLVMGetTypeKind(LLVMGetReturnType(LLVMGetElementType(LLVMTypeOf(self.as_value_ref()))))
+        };
+
+        matches!(return_type, LLVMTypeKind::LLVMVoidTypeKind)
+    }
+}
+
+impl<'ctx> From<FunctionValue<'ctx>> for CallableValue<'ctx> {
+    fn from(value: FunctionValue<'ctx>) -> Self {
+        Self(Either::Left(value))
+    }
+}
+
+impl<'ctx> TryFrom<PointerValue<'ctx>> for CallableValue<'ctx> {
+    type Error = ();
+
+    fn try_from(value: PointerValue<'ctx>) -> Result<Self, Self::Error> {
+        // If using a pointer value, we must validate it's a valid function ptr
+        let value_ref = value.as_value_ref();
+        let ty_kind = unsafe { LLVMGetTypeKind(LLVMGetElementType(LLVMTypeOf(value_ref))) };
+        let is_a_fn_ptr = matches!(ty_kind, LLVMTypeKind::LLVMFunctionTypeKind);
+
+        if is_a_fn_ptr {
+            Ok(Self(Either::Right(value)))
+        } else {
+            Err(())
+        }
+    }
+}

src/values/mod.rs

@@ -19,6 +19,7 @@ mod ptr_value;
 mod struct_value;
 mod traits;
 mod vec_value;
+mod callable_value;
 
 use crate::support::LLVMString;
 pub use crate::values::array_value::ArrayValue;
@@ -37,6 +38,7 @@ pub use crate::values::metadata_value::{MetadataValue, FIRST_CUSTOM_METADATA_KIN
 pub use crate::values::phi_value::PhiValue;
 pub use crate::values::ptr_value::PointerValue;
 pub use crate::values::struct_value::StructValue;
+pub use crate::values::callable_value::CallableValue;
 pub use crate::values::traits::{AnyValue, AggregateValue, BasicValue, IntMathValue, FloatMathValue, PointerMathValue};
 pub use crate::values::vec_value::VectorValue;
 pub(crate) use crate::values::traits::AsValueRef;

tests/all/test_builder.rs

@@ -1,8 +1,10 @@
 use inkwell::{AddressSpace, AtomicOrdering, AtomicRMWBinOp, OptimizationLevel};
 use inkwell::context::Context;
 use inkwell::values::BasicValue;
+use inkwell::values::CallableValue;
 
 use std::ptr::null;
+use std::convert::TryFrom;
 
 #[test]
 fn test_build_call() {
@@ -57,7 +59,8 @@ fn test_build_call() {
 
     let load = builder.build_load(alloca, "load").into_pointer_value();
 
-    builder.build_call(load, &[], "call");
+    let callable_value = CallableValue::try_from(load).unwrap();
+    builder.build_call(callable_value, &[], "call");
     builder.build_return(None);
 
     assert!(module.verify().is_ok());

tests/all/test_values.rs

@@ -3,7 +3,7 @@ use inkwell::attributes::AttributeLoc;
 use inkwell::context::Context;
 use inkwell::module::Linkage::*;
 use inkwell::types::{AnyType, StringRadix, VectorType};
-use inkwell::values::{AnyValue, BasicValue, InstructionOpcode::*, FIRST_CUSTOM_METADATA_KIND_ID};
+use inkwell::values::{AnyValue, BasicValue, CallableValue, InstructionOpcode::*, FIRST_CUSTOM_METADATA_KIND_ID};
 #[llvm_versions(7.0..=latest)]
 use inkwell::comdat::ComdatSelectionKind;
 
@@ -1134,7 +1134,8 @@ fn test_non_fn_ptr_called() {
     let i8_ptr_param = fn_value.get_first_param().unwrap().into_pointer_value();
 
     builder.position_at_end(bb);
-    builder.build_call(i8_ptr_param, &[], "call");
+    let callable_value = CallableValue::try_from(i8_ptr_param).unwrap();
+    builder.build_call(callable_value, &[], "call");
     builder.build_return(None);
 
     assert!(module.verify().is_ok());