Struct inkwell::execution_engine::ExecutionEngine
source · pub struct ExecutionEngine<'ctx> { /* private fields */ }
Expand description
A reference-counted wrapper around LLVM’s execution engine.
Note
Cloning this object is essentially just a case of copying a couple pointers and incrementing one or two atomics, so this should be quite cheap to create copies. The underlying LLVM object will be automatically deallocated when there are no more references to it.
Implementations§
source§impl<'ctx> ExecutionEngine<'ctx>
impl<'ctx> ExecutionEngine<'ctx>
pub unsafe fn new( execution_engine: Rc<LLVMExecutionEngineRef>, jit_mode: bool ) -> Self
sourcepub fn as_mut_ptr(&self) -> LLVMExecutionEngineRef
pub fn as_mut_ptr(&self) -> LLVMExecutionEngineRef
Acquires the underlying raw pointer belonging to this ExecutionEngine
type.
sourcepub fn link_in_mc_jit()
pub fn link_in_mc_jit()
This function probably doesn’t need to be called, but is here due to linking(?) requirements. Bad things happen if we don’t provide it.
sourcepub fn link_in_interpreter()
pub fn link_in_interpreter()
This function probably doesn’t need to be called, but is here due to linking(?) requirements. Bad things happen if we don’t provide it.
sourcepub fn add_global_mapping(&self, value: &dyn AnyValue<'ctx>, addr: usize)
pub fn add_global_mapping(&self, value: &dyn AnyValue<'ctx>, addr: usize)
Maps the specified value to an address.
Example
use inkwell::targets::{InitializationConfig, Target};
use inkwell::context::Context;
use inkwell::OptimizationLevel;
Target::initialize_native(&InitializationConfig::default()).unwrap();
extern fn sumf(a: f64, b: f64) -> f64 {
a + b
}
let context = Context::create();
let module = context.create_module("test");
let builder = context.create_builder();
let ft = context.f64_type();
let fnt = ft.fn_type(&[], false);
let f = module.add_function("test_fn", fnt, None);
let b = context.append_basic_block(f, "entry");
builder.position_at_end(b);
let extf = module.add_function("sumf", ft.fn_type(&[ft.into(), ft.into()], false), None);
let argf = ft.const_float(64.);
let call_site_value = builder.build_call(extf, &[argf.into(), argf.into()], "retv").unwrap();
let retv = call_site_value.try_as_basic_value().left().unwrap().into_float_value();
builder.build_return(Some(&retv)).unwrap();
let mut ee = module.create_jit_execution_engine(OptimizationLevel::None).unwrap();
ee.add_global_mapping(&extf, sumf as usize);
let result = unsafe { ee.run_function(f, &[]) }.as_float(&ft);
assert_eq!(result, 128.);
sourcepub fn add_module(&self, module: &Module<'ctx>) -> Result<(), ()>
pub fn add_module(&self, module: &Module<'ctx>) -> Result<(), ()>
Adds a module to an ExecutionEngine
.
The method will be Ok(())
if the module does not belong to an ExecutionEngine
already and Err(())
otherwise.
use inkwell::targets::{InitializationConfig, Target};
use inkwell::context::Context;
use inkwell::OptimizationLevel;
Target::initialize_native(&InitializationConfig::default()).unwrap();
let context = Context::create();
let module = context.create_module("test");
let mut ee = module.create_jit_execution_engine(OptimizationLevel::None).unwrap();
assert!(ee.add_module(&module).is_err());
pub fn remove_module( &self, module: &Module<'ctx> ) -> Result<(), RemoveModuleError>
sourcepub unsafe fn get_function<F>(
&self,
fn_name: &str
) -> Result<JitFunction<'ctx, F>, FunctionLookupError>where
F: UnsafeFunctionPointer,
pub unsafe fn get_function<F>(
&self,
fn_name: &str
) -> Result<JitFunction<'ctx, F>, FunctionLookupError>where
F: UnsafeFunctionPointer,
Try to load a function from the execution engine.
If a target hasn’t already been initialized, spurious “function not found” errors may be encountered.
The UnsafeFunctionPointer
trait is designed so only unsafe extern "C"
functions can be retrieved via the get_function()
method. If you
get funny type errors then it’s probably because you have specified the
wrong calling convention or forgotten to specify the retrieved function
as unsafe
.
Examples
let context = Context::create();
let module = context.create_module("test");
let builder = context.create_builder();
// Set up the function signature
let double = context.f64_type();
let sig = double.fn_type(&[], false);
// Add the function to our module
let f = module.add_function("test_fn", sig, None);
let b = context.append_basic_block(f, "entry");
builder.position_at_end(b);
// Insert a return statement
let ret = double.const_float(64.0);
builder.build_return(Some(&ret)).unwrap();
// create the JIT engine
let mut ee = module.create_jit_execution_engine(OptimizationLevel::None).unwrap();
// fetch our JIT'd function and execute it
unsafe {
let test_fn = ee.get_function::<unsafe extern "C" fn() -> f64>("test_fn").unwrap();
let return_value = test_fn.call();
assert_eq!(return_value, 64.0);
}
Safety
It is the caller’s responsibility to ensure they call the function with the correct signature and calling convention.
The JitFunction
wrapper ensures a function won’t accidentally outlive the
execution engine it came from, but adding functions after calling this
method may invalidate the function pointer.
sourcepub fn get_function_address(
&self,
fn_name: &str
) -> Result<usize, FunctionLookupError>
pub fn get_function_address( &self, fn_name: &str ) -> Result<usize, FunctionLookupError>
Attempts to look up a function’s address by its name. May return Err if the function cannot be found or some other unknown error has occurred.
It is recommended to use get_function
instead of this method when intending to call the function
pointer so that you don’t have to do error-prone transmutes yourself.
pub fn get_target_data(&self) -> &TargetData
pub fn get_function_value( &self, fn_name: &str ) -> Result<FunctionValue<'ctx>, FunctionLookupError>
pub unsafe fn run_function( &self, function: FunctionValue<'ctx>, args: &[&GenericValue<'ctx>] ) -> GenericValue<'ctx>
pub unsafe fn run_function_as_main( &self, function: FunctionValue<'ctx>, args: &[&str] ) -> c_int
pub fn free_fn_machine_code(&self, function: FunctionValue<'ctx>)
pub fn run_static_constructors(&self)
pub fn run_static_destructors(&self)
Trait Implementations§
source§impl Clone for ExecutionEngine<'_>
impl Clone for ExecutionEngine<'_>
source§impl<'ctx> Debug for ExecutionEngine<'ctx>
impl<'ctx> Debug for ExecutionEngine<'ctx>
source§impl Drop for ExecutionEngine<'_>
impl Drop for ExecutionEngine<'_>
source§impl<'ctx> PartialEq for ExecutionEngine<'ctx>
impl<'ctx> PartialEq for ExecutionEngine<'ctx>
source§fn eq(&self, other: &ExecutionEngine<'ctx>) -> bool
fn eq(&self, other: &ExecutionEngine<'ctx>) -> bool
self
and other
values to be equal, and is used
by ==
.