Struct weld::WeldModule

pub struct WeldModule { /* fields omitted */ }

A compiled runnable Weld module.

Methods

impl WeldModule

pub fn compile<S: AsRef<str>>(
    code: S,
    conf: &WeldConf
) -> WeldResult<WeldModule>

Creates a compiled WeldModule with a Weld program and configuration.

A compiled module encapsulates JIT'd code in the current process. This function takes a string reprsentation of Weld code, parses it, and compiles it into machine code. The passed WeldConf can be used to configure how the code is compiled (see conf.rs for a list of compilation options). Each configuration option has a default value, so setting configuration options is optional.

Errors

• If the provided code does not compile (e.g., due to a syntax error), a compile error is returned.
• If the provided configuration has an invalid configuration option, a compile error is returned.

Examples

Compiling a valid program:

use weld::*;

let conf = &WeldConf::new();
let code = "|| 1";

let mut module = WeldModule::compile(code, conf);
assert!(module.is_ok());

Invalid programs or configurations will return compile errors:

let conf = &mut WeldConf::new();

// Type error in program!
let mut module = WeldModule::compile("|| 1 + f32(1)", conf);
assert!(module.is_err());

let err = module.unwrap_err();
assert_eq!(err.code(), WeldRuntimeErrno::CompileError);

conf.set("weld.memory.limit", "invalidLimit");
let mut module = WeldModule::compile("|| 1", conf);
assert!(module.is_err());

let err = module.unwrap_err();
assert_eq!(err.code(), WeldRuntimeErrno::CompileError);

pub unsafe fn run(
    &self,
    context: &mut WeldContext,
    arg: &WeldValue
) -> WeldResult<WeldValue>

Run this WeldModule with a context and argument.

This is the entry point for running a Weld program. The argument is a WeldValue that encapsulates a pointer to the argument. See the section below about how this argument should be structured.

The context captures state: in particular, it holds the memory allocated by a run. Contexts can be reused across runs and modules. Contexts are primarily useful for passing mutable state---builders---in and out of Weld and updating them in place. For example, a program can compute some partial result, return a builder, and then pass the builder as a WeldValue back into run with the same context to continue updating that builder.

Contexts are not thread-safe---this is enforced in Rust by having this function take a mutable reference to a context. If a context is cloned, this constraint is maintained via interior mutability: contexts internally hold a RefCell that is mutably borrowed by this function, so a panic will be thrown if multiple callers try to run a module with the same context.

Structuring Arguments

This function takes a WeldValue initialized using WeldValue::new_from_data or another Weld program. The value must encapsulate a valid pointer in a "Weld-compatible" format as specified by the specification. This method is, as a result, unsafe because passing invalid data into a Weld program will cause undefined behavior.

Note that most Rust values cannot be passed into Weld directly. For example, it is not safe to simply pass a raw pointer to a Vec<T> into Weld directly.

Errors

This method may return any of the errors specified in WeldRuntimeErrno, if a runtime error occurs during the execution of the program. Currently, the implementation panics if a runtime error is thrown.

Panics

The current implementation panics whenever the runtime throws an error. This function will also panic if the same context is passed to run at once (this is possible if, e.g., if a context is cloned).

Examples

use weld::*;
use std::cell::Cell;

// Wrap in Cell so we can get a raw pointer
let input = Cell::new(1 as i32);
let conf = &WeldConf::new();

// Program that adds one to an i32.
let mut module = WeldModule::compile("|x: i32| x + 1", conf).unwrap();
let input_value = &WeldValue::new_from_data(input.as_ptr() as Data);
let context = &mut WeldContext::new(conf).unwrap();

// Running is unsafe, since we're outside of Rust in JIT'd code, operating over
// raw pointers.
let result = unsafe { module.run(context, input_value).unwrap() };

assert!(result.context().is_some());

// Unsafe to read raw pointers!
unsafe {
    // The data is just a raw pointer: cast it to the expected type.
    let data = result.data() as *const i32;

    let result = (*data).clone();
    assert_eq!(input.get() + 1, result);
}

pub fn param_types(&self) -> Vec<Type>

Returns the Weld arguments types of this WeldModule.

pub fn return_type(&self) -> Type

Returns the Weld return type of this WeldModule.

Trait Implementations

impl Debug for WeldModule

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.